codeherd-session-status

codeherd

A CLI for managing parallel agentic coding sessions. It organizes projects and git worktrees, configures per-agent environments with deterministic port allocation, and orchestrates tmux sessions where AI coding agents run independently.

It is like a shepherd, but for coding agents.

Why

Running multiple AI coding agents in parallel requires isolated workspaces, separate environments, and session management. codeherd handles the infrastructure -- git worktrees for isolation, tmux sessions for persistence, deterministic ports to avoid conflicts -- so each agent gets a clean, independent workspace without manual setup.

How It Works

codeherd manages a lifecycle that takes a project from configuration to a running agent session:

Clone -> Worktree -> File Copy -> Template Processing -> Session Start

Each step has pre/post hooks for custom automation (install dependencies, start services, notify external systems). See docs/hooks.md for the full hook lifecycle reference.

Configuration

All configuration lives in ~/.config/codeherd/config.toml. Here is a full example:

[defaults]
projects_dir = "~/projects"    # base directory for clones and worktrees
agent = "claude"               # default agent for new sessions

# ── Agents ──────────────────────────────────────────────────────────────────

[agents.claude]
cmd = "claude"
args = ["--dangerously-skip-permissions"]

[agents.claude.env]
CLAUDE_CONFIG_DIR = "/home/user/.config/claude"

[agents.aider]
cmd = "aider"
args = ["--model", "opus"]

[agents.codex]
cmd = "codex"
args = ["--approval-mode", "full-auto"]

# ── Projects ────────────────────────────────────────────────────────────────

[projects.myapp]
repo = "[email protected]:user/myapp.git"
default_branch = "main"

# Files copied into every new worktree (see File Copy section)
files = [
  "CLAUDE.md",                                       # same path in worktree
  ".cursorrules",                                     # same path in worktree
  "~/.config/codeherd/prompts/safety.md:RULES.md",   # absolute source, custom destination
]

# Hooks run at each lifecycle step (see Hooks section)
[projects.myapp.hooks]
post-clone = "make deps"
post-worktree = "npm install"
pre-session = "docker compose up -d"
post-session = "curl -s https://hooks.example.com/started"

[projects.api]
repo = "[email protected]:user/api.git"
default_branch = "develop"
files = [".envrc"]

[projects.api.hooks]
post-worktree = "bundle install"

Projects

Each project points to a git repository and a default branch. Clone paths mirror the repo URL under projects_dir:

~/projects/
  github.com/user/
    myapp/                    # main clone
    myapp__worktrees/
      feature/                # worktree for "feature" branch
      fix-123/                # worktree for "fix-123" branch
    api/                      # another project

Agents

Agents are CLI tools configured once and selected at session start. Any command-line tool works -- Claude Code, Aider, Codex, or a custom script. Each agent defines a command, optional arguments, and optional environment variables.

Sessions

Sessions are tmux sessions anchored to a project and branch. They run independently and persist across disconnects:

tmux sessions:
  codeherd         # TUI dashboard
  myapp-feature    # Claude Code working on feature
  myapp-fix-123    # Aider fixing a bug
  api-experiment   # another agent exploring an idea

Lifecycle

When you create a worktree and start a session, codeherd runs through a five-step lifecycle. Each step has optional pre/post hooks.

 Clone ──> Worktree ──> File Copy ──> Template Processing ──> Session Start
  │  │      │  │         │  │          │  │                    │  │
 pre post  pre post     pre post      pre post                pre post

File Copy

The files list in project config copies files into new worktrees. This is useful for shared configuration (editor rules, prompt files, env configs) that should exist in every worktree but isn't tracked in git.

Entry format	Source	Destination
"CLAUDE.md"	Clone dir / CLAUDE.md	Worktree / CLAUDE.md
"src/config.json"	Clone dir / src/config.json	Worktree / src/config.json
"~/.config/prompts/safety.md:RULES.md"	~/.config/prompts/safety.md	Worktree / RULES.md
"/absolute/path/file.txt:subdir/file.txt"	/absolute/path/file.txt	Worktree / subdir/file.txt

Relative paths resolve from the clone directory. Absolute paths and ~/ paths copy from the filesystem. Intermediate directories are created automatically.

Template Processing

After files are copied, codeherd scans the worktree for .herd files and renders them using Go's text/template engine. The rendered output is written as a sibling file without the .herd suffix: