Skip to content
agentsmith
Esc
↑↓navigate↵open⌘Jpreview
On this page

Personal user walkthrough

Keep Codex and Claude Code context synchronized across a laptop and a long-running workstation.

Suppose you use a MacBook for app development and a long-running workstation for server work. Both run Codex and Claude Code. Most of your preferences are shared, but only the laptop needs iOS guidance and only the workstation needs server operations guidance.

The goal is not one giant file copied everywhere. The goal is one reusable source repository with a small profile per machine.

1. Create the context repository

Create a Git repository with this shape:

agent-context/
├── agentsmith.toml
├── profiles/
│   ├── laptop.toml
│   └── workstation.toml
├── templates/
│   └── personal/
│       └── default.md
└── packs/
    ├── base/
    │   └── instructions/
    │       └── workflow/
    │           └── 10-base.md
    ├── ios/
    │   └── instructions/
    │       └── tools/
    │           └── 10-xcode.md
    └── server/
        └── instructions/
            └── tools/
                └── 10-server.md

Start the root config with optional size guardrails:

[budgets]
instruction_layer_bytes = 24576
skill_markdown_bytes = 16384

2. Define the document once

The template controls structure, while packs supply the variable details:

# Personal working agreement

## Workflow

<!-- agentsmith:required-slot workflow -->

## Tools available on this machine

<!-- agentsmith:slot tools -->

The required workflow slot prevents a profile from generating an empty working agreement. The tools slot is optional because not every machine needs extra tool guidance.

3. Put concerns into packs

An instruction-only pack is just a directory:

- Inspect the repository before editing.
- Preserve unrelated worktree changes.
- Run focused verification before reporting completion.

The laptop-specific pack contributes to the same template without replacing it:

- Use the checked-in Xcode project and the repository's selected scheme.
- Prefer Simulator for routine iteration.

The server pack can describe its own environment independently:

- Treat background services as long-running processes.
- Check existing listeners and logs before restarting a service.

None of these packs needs pack.toml. That optional manifest exists only for packs that enable skills.

4. Select packs per machine

harnesses = ["codex", "claude-code"]
template = "personal"
packs = ["base", "ios"]
harnesses = ["codex", "claude-code"]
template = "personal"
packs = ["base", "server"]

Pack order is rendered order. Both machines receive base; each adds only its relevant tool section.

5. Point each machine at its profile

Clone the repository to the same conventional location on each machine, then create the local machine config.

On the laptop:

source = "~/.agents/agentsmith/source"
profile = "laptop"

On the workstation, use the same file with profile = "workstation".

The machine config is intentionally local. It answers “which machine am I?” while the Git repository answers “what profiles and reusable content exist?”

6. Preview before writing

asmith global lint
asmith global explain
asmith global diff

explain is especially useful here: it shows the selected profile, template, packs, output destinations, slots, and byte sizes. If an unexpected instruction appears, its provenance tells you which pack added it.

7. Synchronize

asmith global sync

The command requires a clean Source Repository, performs git pull --ff-only, and then generates:

~/.codex/AGENTS.md
~/.claude/CLAUDE.md

If selected packs enable skills, agentsmith also generates them under the native global skill roots.

Run global sync manually, from a scheduler, or from whatever machine-management workflow fits your environment. It does not depend on login or reboot, so it works for long-running hosts.

8. Make a change once

To add a shared rule, edit the base snippet, commit, and push the Source Repository. On each machine:

asmith global diff
asmith global sync

If a generated global file was hand-edited, agentsmith detects that its content no longer matches recorded state and stops. Review the edit instead of silently losing it.

What this example used

  • Profiles select different behavior per machine.
  • Packs keep shared, iOS, and server concerns independent.
  • Slots place those concerns inside the right Markdown sections.
  • Required slots prevent an incomplete baseline.
  • Diff and explain make the result reviewable.
  • Global sync updates long-running machines without relying on shell login.

Was this page helpful?