Repolane

One ticket. Every repo it touches. One bounded AI session.

Repolane is a local workspace for multi-repository development with Claude Code. It gives each piece of work an isolated lane across every repository it touches, preserves the context needed to resume later, and enforces tested guardrails around what the coding agent can access and do.

The command is lane.

Website · Documentation · Security model · Apache 2.0

---

The problem: A feature spans your frontend, API, and worker. Each lives in a separate Git repository. You end up juggling checkouts, branches, and separate AI sessions while trying to keep the implementation consistent — four checkouts of web, two of api, a Monday branch sitting in a directory you last opened on Thursday, and no record of which clone a stash landed in.

Point Claude Code at one of those folders and it gets worse, not better: the session only sees one repo, so cross-repo work becomes a sequence of context-free single-repo sessions. Ask it to fix one bug and it wanders into three other repos looking for context, filling its window with code nobody asked about. It learns something useful about your deploy process and writes it down as a permanent global preference. It commits when you wanted to look first.

The solution: Repolane makes the ticket — not the repository — the unit of work. One lane groups a Git worktree for each participating repository, a shared task goal, progress notes, and repository state. Start Claude Code at the lane root to work across those repositories without losing the task's boundaries.

• Work across repositories: one task ID and coordinated worktrees across the repositories involved.
• Resume without reconstructing context: keep the goal, findings, progress notes, and Git state together.
• Enforce task-scoped guardrails: Claude Code hooks deny disallowed operations, including access to secrets and unrelated lanes.
• Keep control local: no hosted service or account required; task state and the local board stay on your machine.

Repolane is built on Git worktrees, Bash, and standard-library Python. It does not replace Claude Code or Git, and its guardrails are not an operating-system sandbox.

Contents: See it in action · Is Repolane for you? · Quick start · Complete workflow example · How it works · Why it refuses things · The commands · Using it without Claude · Documentation · Your workspace · Status and contributing

See it in action

pipx install repolane            # or: uv tool install repolane
lane init ~/work && cd ~/work    # a workspace: any folder where lane init ran
lane add <git-url>               # each repo is cloned once, as a mirror
lane start ABC-123 web api       # a branch and a worktree of each repo, grouped as one lane
cd lanes/ABC-123 && claude       # Claude opens knowing what this work is and which repos are in scope
lane park ABC-123 "waiting on review for the api side"   # resume note + wip-commit, nothing left loose
lane done ABC-123                # removes the folders once everything is pushed

Is Repolane for you?

Useful when a single change spans multiple repos and you want the coding agent to work across them with explicit boundaries and resumable context. If you work in one repo at a time, plain Git worktrees may be all you need.

Quick start

Prerequisites

git	required — worktrees are the whole mechanism
python3	required (3.9 or later) — the package, the hook dispatcher and the board are stdlib Python, no dependencies
bash	required — every command is a bash script
pipx or uv	to install the package (plain pip into a venv works too)
gh	optional — pull request status and lane gh
Claude Code	optional — the commands work on their own; the hooks only matter when Claude is driving

Nothing is compiled and nothing phones home. Tested on macOS and Linux; on Windows use WSL.

pipx install repolane             # or: uv tool install repolane — puts `lane` and the long-form commands on PATH
mkdir ~/work && cd ~/work
lane init                         # makes this folder a workspace; asks before touching CLAUDE.md or ~/.claude
lane add <git-url>                # or: lane add ~/path/to/a/checkout/you/already/have

lane init asks for your name, whether to add Repolane's import line to a CLAUDE.md you already have, and whether to link Claude Code's memory for this folder into the workspace. --yes takes the defaults, and --git makes the workspace a git repo of your own. docs/install.md has the details, the full layout, and how to move over from an older git-clone install with lane migrate.

lane add takes a checkout you already have, not just a URL — it adopts the existing .git, keeps the origin, and remembers where it came from so lane import can find the Claude conversations you already had about that repo.

lane import is entirely optional and safe to poke at: lane import --list only shows what was found on this machine and changes nothing, and bringing a conversation in copies it into the lane's folder — the original conversation, wherever it was, is left exactly where it was.

Complete workflow example

A lane is one piece of work. It may span any number of repos.

lane start ABC-123 web api

That gives you a branch named ABC-123 in both repos and a folder holding a worktree of each:

lanes/ABC-123/
  web/     a worktree of .repolane/repos/web on branch ABC-123
  api/     a worktree of .repolane/repos/api on branch ABC-123
  refs/    anything you attached for reference

Each repo is cloned once, into .repolane/repos/<name>, and that copy is a mirror: always on its default branch, never edited, never switched. Every lane's worktrees share its object store, so the second piece of work costs a checkout of files rather than a full clone, and switching between them is instant. Ten lanes across six repos is still six clones on disk.

You run Claude from lanes/<id>/ — the lane itself, not one of the repos inside it. No repo is the main one. That single detail is what keeps multi-repo work from collapsing back into single-repo work.

cd lanes/ABC-123 && claude       # opens knowing what this work is
lane park ABC-123 "waiting on review for the api side"
lane done ABC-123                # removes the folders once everything is pushed

lane park writes a resume note and wip-commits anything dirty, so nothing is left loose in a worktree. lane done refuses while any repo is dirty or holds unpushed commits — and it checks every repo before it removes any of them, so a lane whose second repo has unpushed work does not lose the first repo's worktree on the way to failing.

How it works

Three pieces, each doing one job.

1. The workspace

A workspace is any folder where lane init ran. Your CLAUDE.md, .claude/ and lanes/ sit at its top; everything else Repolane keeps is under .repolane/. lanes/ holds the work. .repolane/repos/ holds the clean mirrors. .repolane/registry/ is the source of truth that describes both — repos.yaml lists the repos, and registry/lanes/<id>.md is one file per lane carrying its goal, resume note, findings, log, and the list of repos in scope.

That lane file is also the allow-list for a session: the repos it names are the repos the work may touch. The mirrors and the worktrees are machine state that the registry can rebuild. Deleted a worktree by hand? lane resume <id> prunes the stale registration and recreates it.

Inside a lane, Claude Code refuses Edit and Write outside the lane folder, so a lane session saves its Goal and memory drafts with lane-memory goal "<text>" and lane-memory draft <slug> "<text>", which the rules tell it to use.

2. The guard

The guard (scripts/hooks/guard.py in the package) is a hook dispatcher wired into Claude Code's PreToolUse, PostToolUse, UserPromptSubmit, PreCompact, SessionEnd, SessionStart and worktree events, through lane hook <event> commands in .claude/settings.json and every lane's settings. It reads the hook JSON on stdin and answers allow, deny, or "here is some context you are missing."

It is not a prompt asking nicely. It inspects the actual tool call — including the text of every Bash command, each segment of a chain, and every path any of them names — and it judges paths by what was written, so a symlink or a .. that climbs out of the lane is refused exactly like its absolute twin.

Repolane uses Claude Code hooks to inspect tool calls and deny disallowed operations. Its guardrails are tested, and lane doctor checks that they remain wired and functioning — including that lane is on PATH, because a hook that cannot start fails open. This is not an operating-system sandbox, and unexpected hook input can fail open: the dispatcher fails open on malformed input, because a crashed guard that blocks everything is worse than one that lets an odd call through.

It also adds context rather than only removing options: the first time a session touches a repo it injects that repo's own CLAUDE.md and rules list, and the first prompt in a lane carries the memory index for every repo in scope.

lane doctor compiles it and fires eleven named probes at it — ten that must be refused and one ordinary command that must not — so you find out when the rules stop being enforced. Behind that there is a suite of well over 1,800 cases, which lane doctor -v runs.

3. The board

lane board serves a local web page: every lane, what each one touches, the files you changed, the diff of the one you picked, a commit box, history across all repos of a lane at once, notes, refs and the memory browser. It is plain HTML, CSS and JavaScript with no build step, served by a stdlib Python server bound to 127.0.0.1 with a per-run token. Secret files are dropped by path before git is ever asked for their content.

Why it refuses things

Every rule below exists because the alternative went wrong at least once. docs/rules.md tells each story.

• A session stays in its lane. The guard denies reads of another lane, the mirrors, or anything outside the workspace. Need something from outside? lane ref <id> add <path> attaches it once, and it is readable at lanes/<id>/refs/<name>. A reference is read-only to a Claude session — the hook refuses writes through it unless you pass --rw. On disk it is a symlink, so your own editor can still write to it.
• Nobody enters a repo. The session sits at the lane root. lane run <repo> <cmd>, lane gh <repo> <args>, git -C <repo> and editing <repo>/file all work without moving, and a cd into a repo is refused — in Claude Code a cd moves the session itself, so one cd for convenience strands it.
• Secrets are denied by default, not an exception you opt into. The guard recognizes a fixed set of shapes — .env*, *.pem/*.key/*.p12/*.pfx, *credentials*.json, secrets.json/.yaml/.toml — by filename, across every repo, and refuses the file tools and any Bash command naming one of them, even with permission granted, because the read itself is the problem: the values end up in a transcript. cp .env /tmp/x && cat /tmp/x is the whole attack, so copying and linking are refused too. Structure comes from .env.example or lane keys <path>, which lists names and never values. This is pattern matching, not a sandbox boundary: a credential file outside that fixed set (service-account.json, .npmrc, id_rsa, …) is not recognized and is not denied unless you declare it with lane secrets <repo> add — see docs/rules.md.
• Default branches are protected. Pushing to main, master or develop needs a marker you can see — ALLOW_DEFAULT_BRANCH_PUSH=1 git push …. Remotes may never be added, changed or removed. Destructive gh calls (repo delete, writing gh api) are refused outright.
• Memory is never written silently. Claude drafts it, then asks which of four scopes it belongs in, chosen by how long it stays true: (always), (every repo), (that repo, after this ships) or (only while this work is live). Left alone, everything becomes a permanent global preference, and within a month the system is full of things that were true once.

The commands

lane init       make a folder a workspace       lane add      bring a repo under management
lane status     where everything stands        lane board    the same thing in a browser
lane brief      catch up on one piece of work  lane audit    branches that look finished or stale
lane find       which lane touched this file, branch or commit
lane run/gh     run something in one repo without leaving the lane
lane ref        attach outside code or docs    lane note     write something worth remembering
lane merge      two pieces of work turned out to be one
lane import     adopt past Claude conversations
lane doctor     check the workspace is wired and the safety rules are working (--fix repairs)
lane sync       check a repo's real GitHub branch protection
lane rules      pull a team's shared, SHA-pinned rules.yaml
lane upgrade    upgrade the package and refresh every workspace (--check only looks)
lane migrate    turn an older git-clone install into a workspace
lane help       the full list

Every command also exists as its own executable — lane-start, lane-run, lane-memory — installed next to lane, so they run from any directory with no cd. Full reference in docs/commands.md. Your own commands work the same way: anything executable in .repolane/scripts/local/ becomes lane <name> with no dispatcher edit needed — see docs/extending.md.

Using it without Claude

Nothing above requires an AI. lane start, lane status, lane brief, lane board and the rest are a perfectly ordinary multi-repo worktree manager, and plenty of the value — one clone per repo, a folder per piece of work, a resume note you wrote to yourself — has nothing to do with a model. The hooks simply do not fire when Claude is not the one running.

Documentation

Everything is readable on the site at repolane.dev/docs, and in this repo:

docs/install.md	installing, the workspace and its files, lane init, lane doctor, lane upgrade, lane migrate
docs/concepts.md	the six words the whole system is built from — start here
docs/rules.md	every refusal, and the failure behind it
docs/commands.md	the full command reference
docs/board.md	the web board
docs/troubleshooting.md	the ways it actually breaks, and how to recover
docs/releasing.md	how a merged PR actually becomes a release
docs/extending.md	.repolane/scripts/local/ custom commands, and lane rules pull for shared rules

In the source, scripts/, scripts/hooks/ and scripts/board/ each have a README explaining what lives there.

Your workspace

The package is Repolane; the workspace is yours. lane upgrade replaces the package and refreshes the few files Repolane keeps in a workspace (.repolane/REPOLANE.md, LANE.md, version, and its own hooks in your settings), and never touches anything you wrote. Your CLAUDE.md imports Repolane's rules with one line, @.repolane/REPOLANE.md, and is otherwise entirely yours.

What is worth keeping is small text: CLAUDE.md, .claude/settings.json, .repolane/config.yml, env.sh, knowledge/, memory/ and the registry. lane init --git makes the workspace a git repo that ignores the rest (lanes/, the mirrors, the cache); push it to a private remote of your own, clone it on another machine and run lane init there. See docs/install.md.

Status and contributing

Repolane is used daily by its author and is stable for that use. It is early software: the layout on disk is settled, the command names are settled, and the guard has a real test suite — but expect rough edges outside the paths that get walked every day. lane --version prints the installed version, and lane upgrade --check compares it with the newest on PyPI; see CHANGELOG.md for what changed.

Issues, discussions and pull requests are welcome, and used: if something is broken, unclear, or missing, filing it is the useful thing to do. Issues are for bugs and feature requests — there are templates asking for the command you ran and what it did. Discussions are open for everything more open-ended: questions, "is this a bug or am I holding it wrong", and feedback on where this should go.

Pull requests are welcome too — see CONTRIBUTING.md for how to run the guard's test suite, what the project expects of a change, and how to propose one. The short version: if you change scripts/hooks/guard.py, run bash scripts/hooks/test-guard.sh in a checkout of this repo (it builds its own throwaway sandbox, so it runs anywhere and never touches your lanes) and add a case for whatever you changed. A rule with no test is a rule that will quietly stop working.

Participation is covered by the Code of Conduct.

Use with care

Claude and other AI models can make mistakes: they can edit the wrong file, run the wrong command or misread a rule. Repolane's hooks reduce that risk but cannot remove it, and they are a guardrail, not a sandbox. Review what Claude changes, push only what you have read, and keep credentials you cannot afford to lose out of reach. You are responsible for what runs on your machine and in your repositories. Repolane is provided "as is", without warranty, under the Apache License 2.0.

License

Apache License 2.0 — see LICENSE and NOTICE.

⚠️ Workflow Safety & Git Integrity

This tool automates local Git operations, file synchronization, and git worktree management across repositories.

• Commit or Stash Your Work: Before running multi-repo orchestration tasks, ensure all repositories have clean working trees or that your active work is committed or stashed.
• Non-Destructive by Design: This framework creates local branches and isolated worktrees. It does not automatically run force-push, and never runs a destructive reset against a checkout you point it at — the one hard reset that happens automatically is on the mirror lane add creates for itself, a fresh copy it made moments earlier, never your own working tree.
• Review Generated Worktrees: Stale or abandoned worktrees can be reviewed at any time using git worktree list and cleaned up manually or via git worktree prune — or with lane nested --fix and lane resume, which do the same thing with the lane's own state in view; see docs/troubleshooting.md.