# onetree > onetree lets several coding agents (Claude Code sessions, their subagents, Codex) work at the same time in one git clone and one working tree, without a git worktree per agent and without overwriting each other's files. Each session stages in a private git index, claims the paths it will write, and lands through a commit broker that audits the claims, runs an operator-admitted payload gate and the repository's test suite, and moves the branch by compare-and-swap. onetree is a command-line tool, not a service: one host, one clone, no daemon, no network. Its state is an append-only event log kept in the repository itself, on the ref `refs/onetree/wal`. - Status: pre-release, version 0.0.1a0. Problems and questions go to https://github.com/EliasCodeFI/onetree/issues - Needs: Linux, Python 3.11 or newer, and Git. No other dependencies. Windows is not supported. - Install: onetree is not on PyPI, and `pip install onetree` does not install this project. Install it from its repository with `uv tool install git+https://github.com/EliasCodeFI/onetree`, or `pipx install git+https://github.com/EliasCodeFI/onetree`, or, inside a virtual environment, `python -m pip install git+https://github.com/EliasCodeFI/onetree`. Check the installation with `onetree status`, which prints `onetree 0.0.1a0`. - Set up a repository once with `onetree init --test ""`: it admits onetree's standard payload gate (refuses unresolved merge conflict markers, private keys and files over 50 MiB), sets the test command that must pass before every landing, and turns on the log cache. - Claude Code: install the plugin with `/plugin marketplace add EliasCodeFI/onetree` and `/plugin install onetree@onetree`. It claims each file before Claude edits it (an edit to a file another session or subagent holds is refused, naming the holder), refuses git commands that would erase another agent's work (`checkout`, `restore`, `reset`, `stash`, `clean`, `commit`, `switch`, `merge`, `rebase`, `pull`), gives each subagent claims of its own, and adds MCP tools `claim`, `release`, `claims` and `land`; the `land` tool also works when Claude Code's shell sandbox is on. - Codex: add a PreToolUse hook for `apply_patch` and `Bash` that runs `onetree hook codex pre-tool-use` to `.codex/hooks.json`, trust it with `/hooks`, and land with `onetree land -a -m ""`. - Compared with a git worktree per agent: one copy instead of many, so a second edit of the same file is refused instead of surfacing later as a merge conflict, and each change is tested on the current branch before it lands. Compared with lock hooks and Claude Code agent teams: onetree also refuses the second edit, and adds a commit broker, the test suite as referee, and a log of every claim and landing. - Commands: `onetree init`, `status`, `session`, `claim`, `claims`, `check`, `narrow`, `release`, `land` (`land -a` stages every file the session holds first), `gate`, `protect`, `reconcile`, `wal`, `autosave`, `gc`, `hook` and `mcp`. Every command except `hook` and `mcp` accepts `--json` and then writes exactly one JSON object to standard output. - Session identity: `--session `, then `ONETREE_SESSION_ID`, then the ids agents set themselves (`CLAUDE_CODE_SESSION_ID`, `CODEX_THREAD_ID`). A claim may name a file that does not exist yet. - Good to know: claims cover repository files, not ports, databases or other things agents share at run time; onetree works on one machine and one clone, and pushing to a remote is up to you; a shell command that writes a file directly, such as `sed -i`, is not stopped, though a landing still refuses any file the session does not hold. - Licence: Apache-2.0. Source: https://github.com/EliasCodeFI/onetree How onetree works, in seven steps (the same steps as the animated diagram in the README): 1. **Sessions: a private index for every agent.** Each agent registers a session and gets its own git index. Staging is private; the working tree is shared. 2. **Claims: exclusive write leases on paths.** Before editing, a session claims the exact paths it will write. A claim is an exclusive lease on a path. 3. **A refusal names the holder.** A claim on a held path is refused, and the refusal names the holder. A change to a path you did not claim cannot land. 4. **Edit in the shared tree, stage privately.** Agents edit their claimed files in the one working tree and stage them with ordinary git, each into its own index. 5. **Landing: every change goes through the broker.** onetree land audits the claims, runs the admitted payload gate and your tests, then moves the branch ref by compare-and-swap. 6. **A red candidate stays out.** If the tests fail on the candidate, the landing is refused. The branch does not move, and the refusal is recorded. 7. **One tree, one history.** One clone, one working tree, one linear history. Every claim, landing and refusal is an event in an append-only log kept in git: refs/onetree/wal. What `onetree land` does before a branch moves, in five steps (the second animated diagram): 1. **A candidate is built from the private index.** onetree land builds a candidate commit from the session's private index. The shared index and the working tree are not touched. 2. **Four steps before the branch moves.** Each step can refuse. Only a candidate that passes all four moves the ref. A landing is recorded in the append-only log as an intent and a landed event. 3. **One unclaimed path refuses it all.** If one changed path was not claimed by this session, the whole candidate is refused. Nothing reaches the branch. 4. **A race has exactly one winner.** When two landings race, the compare-and-swap lets exactly one move the ref. The other is rebuilt on the new head and goes through the steps again. 5. **What reaches the branch.** Every commit on the branch is the exact candidate that was audited, gated and tested. A refused candidate leaves the branch where it was. ## Documentation - [README](https://raw.githubusercontent.com/EliasCodeFI/onetree/main/README.md): what onetree is, how to install it, a quick start and the command list - [Design contract](https://raw.githubusercontent.com/EliasCodeFI/onetree/main/docs/DESIGN.md): the mechanism, the state model and the invariants - [Web page as Markdown](https://eliascodefi.github.io/onetree/index.html.md): the project's web page in Markdown ## Project - [Contributing](https://raw.githubusercontent.com/EliasCodeFI/onetree/main/.github/CONTRIBUTING.md): how to contribute - [Security policy](https://raw.githubusercontent.com/EliasCodeFI/onetree/main/.github/SECURITY.md): how to report a vulnerability privately - [License](https://raw.githubusercontent.com/EliasCodeFI/onetree/main/LICENSE): Apache License 2.0