chaban runs several copies of your dev stack on one machine, one per task,
without containers. Chaban means shepherd: it keeps each task in its own
pen. (Why the name.)
Each copy is a workspace. Each workspace gets:
- a git worktree per project, on its own branch;
- its own ports and other numbered values;
- its own generated environment;
- its own daemons and logs.
So two workspaces never fight over port 3000, a database, or a checkout.
It is built for running several coding-agent sessions side by side, one per workspace. chaban starts whatever agent you configure. It also has extras for Claude Code: a skill and a session-start hook. You can use it with no agent at all, too.
chaban records almost nothing. Branches, whether setup is current, which
daemons run: all of it is read live from git, the filesystem and /proc.
There is no "broken" state to repair. Every command converges when you run it
again.
It is one static binary. Linux is the main platform. macOS builds and should work, with simpler liveness checks.
This file is the short version. The details and the reasons behind them are in
docs/reference.md.
A workspace is ordinary processes in ordinary directories: no container, no
VM, no namespace. Nothing collides because everything that could collide goes
through the allocated values. The server listens on ${PORT0}, the database
is my_app_${WORKSPACE}, and each workspace gets its own numbers and its own
name.
So the separation is only as complete as your config makes it. chaban makes
sure no two live workspaces share an allocation. It can't know that your app
hardcodes port 3000 somewhere. If two workspaces fight over something, route
it through values and env. The starter config and
examples/rails.md show how.
Plain processes are simple and fast. There are no images and no volume
mounts, and it works the same on Linux and macOS. Your debugger attaches.
Version-manager shims pick up each worktree's own .ruby-version. A
container-based flavor is on the roadmap, but today's trade is deliberate.
Some do. Claude Code, for example, can give a session its own checkout. That covers the code. chaban covers everything around it: ports, env, databases by name, daemons, and a task identity that outlives any one session. The two work together. A session inside a workspace can still start worktree-isolated subagents.
CGO_ENABLED=0 go install github.com/Phaengris/chaban/v2/cmd/chaban@latest
chaban installYou need a Go toolchain and git. A binary from go install reports its
version as dev, because go install can't set -ldflags. To build from a
checkout with a real version:
CGO_ENABLED=0 go build -ldflags "-X github.com/Phaengris/chaban/v2/internal/cli.version=X.Y.Z" -o chaban ./cmd/chabanchaban install copies the running binary and writes:
| Path | What |
|---|---|
~/.local/bin/chaban |
the binary |
~/.config/fish/functions/chaban.fish |
fish cd wrapper (autoloaded) |
~/.config/fish/completions/chaban.fish |
fish completions (autoloaded) |
~/.local/share/chaban/shell/chaban.bash |
bash/zsh cd wrapper (you source it) |
~/.local/share/chaban/completions/… |
bash/zsh completions (you wire them) |
~/.claude/skills/chaban/SKILL.md |
the Claude Code skill |
~/.local/share/chaban/hooks/session-start.sh |
the Claude Code SessionStart hook |
~/.local/share/chaban/install-manifest.json |
the list uninstall removes |
<root>/config.yml |
a commented starter config, only if absent |
<root>/ |
the workspaces root, created if missing |
Everything comes from inside the binary. Completions are generated from the
live command tree. You can run install again at any time, and it never
overwrites your config.yml. Installing again from the installed binary
itself is safe too.
Make sure ~/.local/bin is on your PATH.
install edits none of your files: no settings.json, no shell rc. It prints
what to add instead:
- The SessionStart hook entry for
~/.claude/settings.json. Claude Code only; see Claude Code extras. - The lines for
~/.bashrcor~/.zshrc. fish needs nothing. The wrapper is there becausechaban cdcan only print a directory: a child process can't change your shell's directory.
chaban uninstall removes exactly what the manifest lists. It never removes
the root, your config or your workspaces. It tells you what it left behind,
including the hook entry in settings.json: that one is yours to remove,
since you added it. The manifest lives in your home and anything could edit
it, so entries no install could have written are refused: a relative path,
/, $HOME, and the root or anything under it. With nothing installed, it
prints nothing installed and exits 0.
chaban was called claude-workspaces before v2.0. If you used it, Upgrading from claude-workspaces moves your setup over.
The root is ~/workspaces. Set CHABAN_ROOT_DIR to use another one; each
root is independent. Describe a project in <root>/config.yml:
# 10 ports per workspace: workspace 0 gets PORT0..PORT9 = 5000..5009,
# workspace 1 gets 5010..5019, and so on.
values:
PORT:
start: 5000
per_workspace: 10
# The command you'd type in a terminal to start your agent.
agent:
start: claude
projects:
demo:
repo: ~/dev/demo # a git repo you have; each workspace gets a worktree of it
setup: # runs once, when the project is checked out
- echo "setup ran"
start: # what `chaban up` runs, in order
- echo "migrations go here" # a plain line runs and finishes
- web: python3 -u -m http.server ${PORT0} # a named line is a daemon
teardown: # runs on `chaban destroy`
- echo "teardown ran"
env: # for the project's commands, and written to its .env
DEMO_URL: http://localhost:${PORT0}
browse_port: ${PORT0} # the port `chaban browse` opensThen:
chaban doctor
chaban new DEMO-1 "try the tool" demo
chaban up DEMO-1
chaban status DEMO-1
chaban logs DEMO-1 web -n 20
chaban cd DEMO-1
chaban chat DEMO-1
chaban down DEMO-1
cd ~
chaban destroy DEMO-1What happened:
newallocated index 0, soPORT0..PORT9are 5000..5009. It created the directory, checked out ademoworktree on branchDEMO-1_try-the-tool, wrote the.envand ransetup:.setup:runs again only when its lines change.upran the plainstart:entry to completion, then started thewebdaemon.chatranclaudein the workspace directory. Put your own agent's command instart; see Agents.destroyranteardown:, removed the worktree and the directory, and released the allocation. The branchDEMO-1_try-the-toolstays in~/dev/demo: a branch is your work.
Two tips. Use python3 -u (or your language's equivalent): a daemon's stdout
is a file, and buffered output makes logs look empty. A daemon started a
second ago may not have written anything yet either, so run logs again. And
cd ~ before destroy, so you aren't standing in the directory it removes.
The steps above show each part on its own. Day to day, one command does it:
chaban launch DEMO-2 "fix the header" demoIt creates DEMO-2 (or reuses it, if it exists), checks out demo and starts
your agent there. Daemons stay down until you or the agent run
chaban up DEMO-2. For an experiment with no project yet,
chaban try "does this library fit" makes a TRY-<n> workspace and starts
the agent in it.
Everything is in one file, <root>/config.yml. It is read strictly: an
unknown key is an error, with its line:column. Each command reads it fresh,
so there is no reload step.
Onboarding a real project has two halves: this file, and making the app use
what the env gives it (no hardcoded ports or database names).
examples/rails.md walks a Rails + Vite + Sidekiq app
through both. The installed skill teaches Claude Code sessions the same steps,
so you can ask a session to "configure workspaces for my project".
All the keys, with real values:
# Numbered values per workspace. With start 5000 and 10 per workspace,
# workspace 0 gets PORT0..PORT9 = 5000..5009, workspace 1 gets 5010..5019.
# REDIS gives each workspace one Redis database: workspace 0 gets REDIS0 = 1.
values:
PORT:
start: 5000
per_workspace: 10
REDIS:
start: 1
per_workspace: 1
# Environment for every project's commands.
env:
RAILS_ENV: development
# chaban starts with your shell's whole environment, but passes only a short
# list of variables to the commands it runs (HOME, LANG, SSH_AUTH_SOCK, ...),
# so a workspace doesn't pick up stray settings. Name here any other
# variable your commands need.
env_allow: [MY_API_TOKEN]
# How `chaban chat` starts your agent. Each line is a terminal command.
agent:
start: claude # a new session
resume: claude --continue # continue the last session
# chooses between the two: exit 0 runs `resume`, exit 1 runs `start`.
# Your own script here; the built-in check for Claude Code is in Agents.
can_resume: ~/.local/bin/claude-has-session-here.sh
instructions_file: CLAUDE.md # the file chaban writes for the agent (default AGENTS.md)
# Shared project definitions; ${NAME} is filled in by each project that uses it.
templates:
rails-client:
params: [NAME]
repo: ~/dev/clients/${NAME}
start:
- rails: bin/rails s -p ${PORT0}
browse_port: ${PORT0}
projects:
my-app:
repo: ~/dev/my-app # required
base_branch: main # new branches start from here (default: the repo's HEAD)
path: my-app # its directory inside the workspace (default: the key)
depends: shared-lib # set up and started after shared-lib, stopped before it
setup: # runs at checkout, and again when these lines change
- bundle install
- bin/rails db:prepare
start: # what `chaban up` runs, in order
- bin/rails db:migrate # a plain line runs and finishes
- rails: bin/rails s -p ${PORT0} # a named line is a daemon
- worker: # a daemon with a description, which `status`
command: bin/sidekiq # and WORKSPACE.md show, so a session
description: background jobs # knows what it is for
stop: # runs on `chaban down`, after the daemons stop
- bin/rails tmp:clear
teardown: # runs on `chaban destroy`, before the worktree goes
- dropdb --if-exists my_app_${WORKSPACE}
env_allow: [STRIPE_KEY] # like env_allow above, for this project only
env: # over the global env; also written to the .env
DATABASE_URL: postgres:///my_app_${WORKSPACE} # my_app_DEMO-1 in workspace DEMO-1
REDIS_URL: redis://localhost:6379/${REDIS0}
PORT: ${PORT0}
browse_port: ${PORT0} # the port `chaban browse` opens
instructions: | # copied into WORKSPACE.md for the agent
A booking system for small clinics. Rails 8, PostgreSQL.
Read my-app/AGENTS.md first.
Tests: `bin/rspec`.
shared-lib:
repo: ~/dev/shared-lib
acme: # uses the template; after filling it in, this is:
template: rails-client # acme:
params: # repo: ~/dev/clients/acme
NAME: acme # start:
# - rails: bin/rails s -p ${PORT0}
# browse_port: ${PORT0}Runtime tokens are ${WORKSPACE} (the task id, like DEMO-1), ${PROJECT}
(the project's key, like my-app), and the values (${PORT0},
${REDIS0}, …). They are filled in inside env, setup, start, stop,
teardown and browse_port. Unknown tokens are left as they are.
- Unquoted
${…}inside flow style is invalid YAML:env: {A: ${PORT0}}fails. Use block style, as above, or quote the value. - A colon followed by a space turns a plain
start:entry into a map:- echo "run: it"becomes a daemon namedecho "run. Quote the whole entry when it contains:. A colon without a space, as in a URL, is fine.
Template merging, the values math, the depends and path rules, .env
seeding and error positions are in
docs/reference.md.
<ws> is a workspace: its task id (DEMO-1) or its full directory name
(DEMO-1_try-the-tool). A task id that matches more than one workspace is an
error that lists them.
| Group | Command | What it does |
|---|---|---|
| Lifecycle | new <task_id> <description> [project…] |
Allocate, create, check projects out. If any step fails, everything is undone. |
checkout <ws> <project…> |
Add projects: worktree, .env, setup. Safe to repeat. |
|
destroy [--force] <ws> |
down, teardown, remove, release. Removes only directories chaban created. |
|
| Allocation | adopt [dir] [--projects a,b] |
Give an existing directory an allocation and env. Never takes ownership of it. Safe to repeat. Defaults to the current directory. |
release [dir] |
Drop the allocation, touch no files. Defaults to the current workspace. | |
gc [-d] |
Release allocations whose directory is gone, clean stale pid files. -d also destroys workspaces created by chaban that have at least one project checked out, all merged, clean, with no daemons. |
|
| Services | up <ws> [target…] (alias start) |
Make sure setup is current, run the run-and-waits, start daemons. Safe to repeat. |
down <ws> [target…] (alias stop) |
Stop daemons (TERM to the group, KILL after 5s), then run stop:. |
|
restart <ws> [target…] |
down, wait until each daemon's main process is gone, then up. |
|
logs <ws> <daemon> [-n N] [-f] |
One daemon's log. -f follows stdout and stderr. |
|
exec <ws> [project] <cmd…> |
Run a command in place of chaban, with the curated environment. | |
browse <ws> [project] |
Open http://localhost:<browse_port>, after checking something listens there. |
|
| Observe | ls [-g] [-a] |
Every workspace, one line each. -g adds project@branch cells (* means changed or untracked files). -a also lists root directories with no allocation: released workspaces (adopt to reuse) and strangers, marked (unmanaged). |
status [ws] |
One workspace in full, read live, plus the ## Status note its agent keeps. With no argument, the ls listing. |
|
env <ws> [project] |
The resolved environment. | |
ports |
Allocated value blocks across workspaces. | |
| Sessions | chat <ws> [-R] [args…] |
Start or resume your agent in the workspace. -R always starts fresh. Other arguments go to the agent. |
launch <task_id> [<description> [project…]] [-R] [-- args…] |
new (or reuse), checkout and chat in one go. Daemons stay down until you up them. |
|
try <description…> [-R] [-- args…] |
A draft workspace with no projects and a generated TRY-<n> id, straight into a session. It still gets its values, so a scratch server has ports. Keep it with checkout, or destroy it. |
|
| Navigate | cd <ws> [project] |
Print the directory; the shell wrapper does the cd. |
which |
The workspace you're in (exit 3 if none). | |
| Meta | doctor |
Health report: config, registry, repos, agent, daemons, stray directories. Reports, never fixes. |
install / uninstall |
See Install. | |
completion <shell> |
The completion script for bash, zsh or fish. |
Three commands create workspaces. new is for scripts, launch is the daily
one, try is the scratchpad.
Exit codes: 0 ok, 1 failed, 2 usage, 3 not found, 4 config error. The query
commands take --json. Targets for up, down, restart and logs are
project names, daemon names, or project:daemon: chaban up DEMO-1 my-app
runs my-app's run-and-waits and starts all its daemons, and
chaban down DEMO-1 my-app:worker stops only the worker.
More on the commands.
Commands chaban runs for you (setup, start:, exec, …) get a curated
environment. Only an allowlist of your variables gets through, plus your
env: on top. PATH loses per-version bin directories, so version-manager
shims pick each worktree's own .ruby-version. To let another variable
through, add it to env_allow:.
Agent sessions (chat, launch, try) get your real login environment
instead, without version pins, plus the workspace's values. Daemons need a
reproducible environment; your agent needs your actual setup.
The allowlist, the PATH rule and the login-shell caveats are in
docs/reference.md.
Read its Limits section once. It will save you a confused hour.
A start: entry is either a run-and-wait (a plain string: migrations,
preludes) or a daemon (a named entry). Each daemon has its own process group
and its own logs. Its liveness is checked by pid and start time, so a reused
pid doesn't fool it.
Daemons are lazy: nothing starts them until chaban up. Give them a
description:. status shows it to every session, so a session knows what to
start.
down sends TERM to each daemon's process group. If the daemon itself is
still alive 5 seconds later, the group gets KILL. With no targets, it stops whatever has a pid file on disk, not what the config lists,
so a daemon you renamed still gets stopped. stop: runs after the daemons are
down.
Liveness, the restart details and how logs behave are in
docs/reference.md.
chaban chat <ws> starts your coding agent in the workspace. The agent:
block in config.yml says which agent and how. Any agent you can start from a
shell works. This is the built-in block for Claude Code:
agent:
start: claude
resume: claude --continue
can_resume: find ~/.claude/projects/$(pwd | sed 's/[^A-Za-z0-9]/-/g') ~/.claude/projects/$(pwd -P | sed 's/[^A-Za-z0-9]/-/g') -maxdepth 1 -name '*.jsonl' 2>/dev/null | grep -q .
instructions_file: CLAUDE.mdThe smallest block is one line. For example, for
Codex, which reads AGENTS.md:
agent:
start: codexEvery chat then starts a new session, and chaban writes AGENTS.md as the
workspace's instructions file. The keys:
startopens a new session. It is the only required key.resumecontinues the last session.can_resumechooses between the two: exit 0 runsresume, exit 1 runsstart. Any other exit, or no answer in 5 seconds, starts nothing and exits 1.-Rskips the check.resumeandcan_resumego together: give both or neither.- All three run as
$SHELL -lc <command>in the workspace directory, with the session environment. Your extra arguments are added, quoted, tostartorresume(whichever runs), never tocan_resume. instructions_fileis the file chaban writes once at the workspace root, with a## Statussection for the agent to fill in. If your block leaves it out, it isAGENTS.md. With noagent:block at all, it isCLAUDE.md, to match theclaudefallback below.
chaban adds no agent flags of its own. --dangerously-skip-permissions
reaches Claude Code only if your block says so.
With no agent: block, chat uses the block above if claude is on your
PATH, and says so on stderr every time:
chaban: no agent: in config.yml, starting claude (found on PATH); add an agent: block to choose
With no claude either, it prints the block as a sample and exits 4.
launch and try check this before they create anything.
The full session rules.
Each workspace's instructions file has a ## Status section. The agent keeps
it up to date, and chaban status shows it. So you, or the next session, can
pick a workspace up again days later without reading old sessions. This works
with any agent: it is a file and a command.
Two pieces only help Claude Code. Another agent still gets everything above.
install writes both either way; without Claude Code they do nothing.
- The skill teaches sessions how to work with chaban: create workspaces
with
launchandtry, start only the daemons the task needs, check work against a running server, keep names short, and end a substantial turn with a handoff report (done / needs you / watch out). - The SessionStart hook prints the workspace's name and live status into every session that opens inside one, including each daemon's description and the status note. It ends with the handoff-report rule. The rules live in the hook, not in the instructions file: that file is written once and then belongs to the agent, while the hook stores nothing, so a change reaches every workspace at once.
chaban never deletes a directory it didn't create.
adoptmanages a directory you made, and never deletes it.releasestops managing a workspace without touching its files.destroyremoves nothing if any stop or teardown fails, so running it again picks up where it stopped. It removes worktrees, which discards uncommitted changes in them, but it never deletes a branch.gc -ddestroys only what is provably done: created by chaban, at least one project checked out, all merged, clean, with no daemons. When in doubt, it keeps. ATRY-draft with nothing checked out is never collected:destroyit yourself.
The exact checks, what --force does and doesn't do, and what doctor looks
at are in docs/reference.md.
Chaban means shepherd. The word came from Persian chupan through Turkic çoban, and lives on in Russian and Ukrainian чабан and Romanian cioban. A shepherd keeps one flock where every animal has its own pen. chaban does the same for parallel agent sessions: each workspace gets its own worktree, ports and daemons. The tool was called claude-workspaces before v2.0.
go test ./... -count=1 # table tests + testscript command flows
gofmt -l . # must print nothing
go vet ./...
CGO_ENABLED=0 go build -ldflags "-X github.com/Phaengris/chaban/v2/internal/cli.version=$(git describe --tags --always)" -o chaban ./cmd/chabanRuntime dependencies: spf13/cobra, goccy/go-yaml, golang.org/x/sys (and
cobra's pflag). Tests only: rogpeppe/go-internal/testscript.
Layout: cmd/chaban is a thin main. internal/cli is the cobra tree, one
file per command. config, alloc, wsp and proc are the domain;
envx, gitx, ui and xerr are leaves. Assets are embedded with
//go:embed. Tests are table tests for pure logic plus testscript flows
against real processes and real git repos. Each test gets its own
CHABAN_ROOT_DIR.
chaban was built with coding agents, the way it is meant to be used. I designed and specified it, and I own every product and architecture decision. The implementation was done by AI (Claude Code, end to end, a clean-room rewrite of an earlier private tool), with an independent review of each task. The paper trail is checked in: commit trailers say who typed, the specs say who decided.
- Spec first:
docs/superpowers/specs/. Every decided behavior has a written row. - Milestone plans:
docs/superpowers/plans/. Binding contracts, named test cases, tables of decided behaviors. - Subagent-driven execution: a fresh AI implementer per task, an independent AI review per task, and a whole-branch review before each merge.
- TDD with mutation-checked tests: load-bearing assertions are checked to fail when the behavior they pin breaks.
- A human owner in the loop: design decisions, reviews of the reviews, and every release.
After 1.0, development runs the same loop on a smaller scale, driven by daily use. Most entries in the CHANGELOG trace back to a real moment at a real terminal.
chaban is an independent open-source project (MIT), not affiliated with, endorsed by or sponsored by Anthropic. Claude and Claude Code are trademarks of Anthropic.