One setup, every agent.
One setup, every agent, every machine. A solo-first CLI, written in Bun and TypeScript and released under MIT: write CLAUDE.md, skills, hooks, and MCP servers once, then fan out to 12 coding agents on every machine. No daemon, no sign-in, no server — just git plus local files.
Start here
Install it, then verify it
Two ways in: a standalone binary via install.sh (macOS arm64/x64, Linux x64/arm64, lands in ~/.local/bin) or npm (needs Node 18+). Exact installer lines are in the repo README; the commands below are the same everywhere once it is on PATH.
soloteam init --local && soloteam doctor
Twelve agents, one source of truth. Claude Code, Codex, Cursor, OpenCode, OpenClaw, Gemini, Copilot, Aider, Windsurf, Kiro, Qoder, and CodeBuddy. Your CLAUDE.md fans out as AGENTS.md to the other agents on pull, so context written once shows up in every tool on every machine.
Sixty seconds
From zero to synced memory
Each step is one command. Run them in order on a fresh machine and you end with shared instructions, a declared MCP server, and a searchable memory.
Initialize the local setup
soloteam init --local
This creates the local soloteam checkout — the directory holding your shared CLAUDE.md, skills, hooks, MCP declarations, and memory files. Everything downstream reads from here.
Check the wiring with doctor
soloteam doctor
Doctor inspects the local setup and reports what is wired and what is missing. Run it after init and whenever something feels off — a broken path shows up here in seconds, not three machines later as a stale agent.
Add an MCP server a single time
soloteam mcp add --name context7 --command npx --args "-y,@upstash/context7-mcp"
The server is declared once in mcp.yaml and written out to each agent's own config format — one line here replaces a manual setup in every tool. § 04 lists exactly which files get written and which lines stay untouched.
Save a lesson, recall it, review the feed
# save what the fix taught you soloteam learn "Port fix" --body "..." # later, on any machine, ask for it back soloteam recall "port conflict" # browse everything in chronological order soloteam timeline
Learn stores a lesson, recall searches it back with plain TF-IDF over local markdown — no index daemon — and timeline streams the feed. Push, and every other machine pulls the same memory; CLAUDE.md travels the same road, fanning out as AGENTS.md on pull.
Sync across machines
Two commands, no magic
Sync is plain git over the main branch. If you already understand commit, push, and fast-forward, you already understand soloteam sync.
Pushing is committing plus pushing main. soloteam push commits the current state of the shared setup and pushes the main branch to the configured remote. Run it where you changed instructions, added a skill, declared a server, or saved a lesson.
Pulling is fast-forwarding. soloteam pull fast-forwards the local checkout to the remote's main — for a solo dev, that means your own changes from the other laptop: instructions, skills, hooks, servers, and memories in one move.
Dirty trees are respected. With uncommitted edits present, soloteam backs off silently instead of merging over in-progress work — commit or stash first, then pull.
Pick the remote that fits your paranoia. A private GitHub repo, or a bare repo on your own server to keep sync traffic on infrastructure you control. One machine only? remote: local is valid, so a lone laptop is a supported setup.
Branch, remote, and the rest live under seven keys in soloteam.yaml — remote, branch, track, mirrors, agents, exclude, friction — covered in the § 06 FAQ.
Everyday recipes
One memory file, every machine
Deliberate memory: you decide what is worth keeping, and every machine remembers it.
soloteam learn "Title" --body "..." # save a lesson soloteam recall "query" # TF-IDF search, local only soloteam timeline # chronological feed soloteam session save # snapshot the session soloteam digest # compress it to essentials
Lessons live as plain local markdown under learnings/, sessions under sessions/ — files you can read, grep, edit, and version like any other notes. Search is plain TF-IDF with no index daemon, recall can be toggled, and an existing claude-mem store can be imported instead of starting empty.
MCP declare-once
One declaration in mcp.yaml, written out to every agent's native format.
soloteam mcp add --name context7 --command npx --args "-y,@upstash/context7-mcp" soloteam mcp list # what is declared soloteam mcp import # pull in an existing server soloteam mcp inject # write it to agent configs soloteam mcp remove # drop a declaration
Declarations cover stdio plus http/SSE servers, and ${VAR} secrets pass straight through — credentials stay as environment references, never baked into files. Injection writes ~/.claude.json, ~/.cursor/mcp.json, and opencode.json, plus a managed block in ~/.codex/config.toml. Hand-written entries outside those targets are left untouched, so machine-specific tweaks survive every sync.
Remember what hurt
A Stop hook that nudges you to record the painful lessons, not the routine ones.
The friction nudge watches for signs a session went sideways and suggests saving a lesson at stop time — at most once per session_id, and only when a weighted score reaches threshold 5: interruptions weigh 3, errors 1, corrections 2. One interruption plus one correction scores 5 and earns a nudge; a clean session stays silent. Lessons saved while the frustration is fresh are the ones every future machine gets to skip.
Scope stays narrow: solo leverage only, team features belong elsewhere. Issues and PRs welcome on GitHub.
Agents & alternatives
Where each agent reads from
One shared source — CLAUDE.md plus skills and hooks, fanning out as AGENTS.md to the other agents on pull — with MCP injected into each tool's native config format. Destinations below are the ones the README verifies; anything hand-written outside them is left alone.
| Agent | Shared source | MCP destination |
|---|---|---|
| Claude Code | CLAUDE.md natively + skills + hooks | ~/.claude.json |
| Codex | AGENTS.md fan-out on pull | managed block in ~/.codex/config.toml |
| Cursor | AGENTS.md fan-out on pull | ~/.cursor/mcp.json |
| OpenCode | AGENTS.md fan-out on pull | opencode.json |
| OpenClaw | AGENTS.md fan-out on pull | — |
| Gemini | AGENTS.md fan-out on pull | — |
| Copilot | AGENTS.md fan-out on pull | — |
| Aider | AGENTS.md fan-out on pull | — |
| Windsurf | AGENTS.md fan-out on pull | — |
| Kiro | AGENTS.md fan-out on pull | — |
| Qoder | AGENTS.md fan-out on pull | — |
| CodeBuddy | AGENTS.md fan-out on pull | — |
Dashes mark agents with no README-verified MCP path — they still receive shared instructions, skills, and hooks. Confirm exact writer coverage in the repo.
How it differs from the neighbors
Two adjacent tools, two different jobs. Dashes mark cells the README makes no claim about.
| Dimension | soloteam-cli | teamai-cli | claude-mem |
|---|---|---|---|
| Who it serves | one dev, N machines | teams | — |
| Sync model | direct push → pull over git | review-flow sync | — |
| Memory style | manual learn / recall, local markdown | — | auto-capture |
| Runtime | hooks + git, no daemon | — | worker service |
soloteam FAQ
Questions the README can answer precisely
Each answer below restates a verified README fact. Nothing is invented.
Does it need a server?
No — no daemon, no sign-in, no server, just git plus local files. A single machine can use remote: local; several machines share a private GitHub repo or a bare repo on your own server.
How is it different from teamai-cli?
teamai-cli is built around teams and review-flow sync. soloteam-cli is solo leverage only: one developer, N machines, direct push-to-pull over git — team features belong elsewhere by explicit scope rule.
How is it different from claude-mem?
claude-mem auto-captures context through a worker service. soloteam-cli memory is deliberate — learn, recall, timeline, session save and digest over local markdown under learnings/ and sessions/, plain TF-IDF, no index daemon. An existing claude-mem store can be imported.
Are the hooks safe? What does the Stop hook do?
Hooks are local files with no daemon; recall can be toggled. The Stop hook is a friction nudge, not an enforcer: it suggests saving a lesson at stop time, at most once per session_id, only when a weighted score reaches threshold 5 — interruptions 3, errors 1, corrections 2. Clean sessions stay silent.
How do I adopt new tracked paths or point at another checkout?
soloteam.yaml holds seven keys: remote, branch, track, mirrors, agents, exclude, friction. Add a path under track: to sync it, scope per-agent under agents:, keep machine files out with exclude:. For another checkout, pass --dir or set SOLOTEAM_DIR / SOLOTEAM_HOME — then run doctor to confirm.
Keep exploring
Related pages
More experiments and utilities from the same lab. Issues and PRs on soloteam-cli itself are welcome on GitHub.