cella-ops

name	cella-ops
description	Use when inside a cella dev container and you need to manage branches, dispatch tasks, run parallel agents, or interact with other containers. Also use when you see CELLA_DAEMON_ADDR in the environment or /cella/bin/cella exists.

Cella Operations

Complete reference for operating the cella worktree-container system from inside a running container. Covers branch management, task dispatch, agent integration, and parallel development.

Mental Model

1 branch = 1 container = 1 agent.

Cella extends dev containers with git worktrees. Each worktree branch gets its own isolated container with its own filesystem, packages, ports, and environment. The host git repo is shared via bind mount, so git operations (commits, merges) are coordinated through the worktree mechanism.

Architecture: A cella daemon runs on the host and manages all containers. Inside each container, a cella agent binary (symlinked as cella) communicates with the host daemon over gRPC. The commands in this skill are agent-side commands — they talk to the daemon to create branches, dispatch tasks, etc. Host-side commands (like cella up without a branch argument to start the daemon) are different and not covered here.

  main (container A)          feat/auth (container B)       feat/api (container C)
  ┌──────────────────┐        ┌──────────────────┐         ┌──────────────────┐
  │  You are here    │        │  AI agent        │         │  AI agent        │
  │  (human)         │◄──────►│  (autonomous)    │◄───────►│  (autonomous)    │
  │  ports: 3000     │  exec  │  ports: 3001     │  exec   │  ports: 3002     │
  └────────┬─────────┘        └────────┬─────────┘         └────────┬─────────┘
           └──────────────────────────┴────────────────────────────┘
                                      │
                              ┌───────┴───────┐
                              │  .git (shared) │
                              └───────────────┘

Containers can communicate bidirectionally via cella exec. The primary worktree container can exec into worktrees and vice versa. Worktree-to-worktree exec also works. Note: cella exec main targets the primary/original worktree container, which may be running any branch (not necessarily a branch named main).

Detection

You are inside a cella container if BOTH of these are true:

• /cella/bin/cella exists (the agent binary)
• CELLA_DAEMON_ADDR environment variable is set (connection to host daemon)

Quick check: cella doctor exits 0.

Choosing: cella exec vs cella task run

Both run commands in another branch's container. The key difference:

• cella exec — synchronous, foreground. Blocks until the command finishes. Output streams to your terminal. Use for quick commands, verification, and interactive work.
• cella task run — asynchronous, background. Returns immediately. Output is captured for later retrieval with cella task logs. Use for long-running work like agent dispatches.

Commands Reference

Container Diagnostics

cella doctor [--json]

Checks connectivity to the host daemon, protocol version match, agent version, and credential helper status. Exits 0 if all checks pass, 1 if any fail. With --json, outputs structured diagnostics including the current version number.

To check your version: cella doctor --json | jq '.daemon_version'

List Branches

cella list [--json]

Shows all worktree branches with their container name and state (running/exited). The current container is marked with *. Use --json for programmatic output.

Create a Branch

cella branch <name> [--base <ref>] [--label key=value]...

Creates a git worktree for <name> on the host, builds and starts a new container for it. Takes ~80s (full container build including image pull and devcontainer lifecycle commands).

• --base <ref> — branch from a specific commit/branch (defaults to HEAD)
• --label key=value — add custom metadata labels to the container (repeatable)

On success, prints: Ready: <worktree_path> (container: <container_name>)

cella branch feat/auth --base main
cella branch feat/api --label team=backend --label priority=high

Run a Command in Another Branch (Synchronous)

cella exec <branch> [--json] -- <command...>

Runs a command in the specified branch's container and streams stdout/stderr to your terminal. The process exit code matches the remote command's exit code. Works bidirectionally — worktree containers can exec to main and vice versa. Worktree-to-worktree also works.

The -- separator before the command is mandatory.

• --json — outputs structured {"exit_code": N, "stdout": "...", "stderr": "..."}

cella exec feat/auth -- cargo test
cella exec main -- echo "hello from main"
cella exec feat/auth --json -- cat src/auth.rs

Switch to Another Branch

cella switch <branch>

Opens an interactive shell session in the target branch's container. For running specific commands, prefer cella exec.

Stop a Branch Container

cella down <branch> [--rm] [--volumes] [--force]

Stops the container for the specified branch.

• --rm — also removes the container, worktree directory, and associated task records. On success, prints: Removed branch '<name>' (container: <container_name>). May fail with ContainerNotFound if the container was already removed — in that case, use cella prune --missing-worktree to clean up the orphaned entry
• --volumes — removes associated volumes (requires --rm)
• --force — overrides the devcontainer.json shutdownAction setting (e.g., when shutdownAction is set to "none" to keep the container running)

Start/Restart a Branch Container

cella up <branch> [--rebuild]

Starts or restarts the container for the specified branch. If the container exists but is stopped, it restarts it. With --rebuild, rebuilds from scratch.

Note: this is the in-container cella up <branch> command. The host-side cella up (no branch argument) starts the daemon and main container — that's a different binary.

Clean Up Worktrees

cella prune [--all] [--dry-run] [--older-than <duration>] [--missing-worktree] [--label key=value]...

Removes worktrees and their containers in bulk.

• --all — removes all linked worktrees including unmerged
• --dry-run — preview what would be removed (lists individual branches)
• --older-than 7d — only prune worktrees older than duration
• --missing-worktree — prune entries whose worktree directory no longer exists
• --label key=value — only prune worktrees matching these labels

Task Dispatch

cella task is available only from inside a cella container. If you're on the host, use cella branch + cella exec instead.

Run a Task (Asynchronous)

cella task run <branch> [--base <ref>] [--timeout <secs>] -- <command...>

Creates the branch + container (if the branch doesn't already exist) and runs the command in the background. Returns immediately. If the branch already exists and has a previous task entry, the new task replaces it.

The -- separator before the command is mandatory.

• --base <ref> — branch from a specific ref when creating a new branch
• --timeout <secs> — kills the task after the specified duration (status becomes timed_out instead of failed)

Task environment parity: tasks get the same user, PATH, working directory, and environment variables (API keys, SSH agent, terminal vars) as interactive cella exec.

List Tasks

cella task list [--json]

Shows all tasks with status, elapsed time, and command:

BRANCH               STATUS     TIME     COMMAND
feat/auth            running    2m       claude --dangerously-skip-permissions -p "..."
feat/api             timed_out  5m       bash -c codex exec "..."
feat/tests           done       45s      claude --dangerously-skip-permissions -p "..."

Statuses: running, done, failed, timed_out

Elapsed time freezes at completion — a task that ran for 45s will always show 45s.

With --json, outputs structured data:

cella task list --json | jq '.[] | select(.status == "running")'

View Task Logs

cella task logs <branch> [--follow]

Shows captured stdout/stderr from the task. With --follow, streams live output.

Wait for Task Completion

cella task wait <branch>

Blocks until the task finishes. The process exit code ($?) matches the task's exit code (see table below). Always prints a status message to stderr: Task '<branch>' exited with code N (non-zero) or Task '<branch>' completed successfully. (zero). Stdout is never written to, so scripts can safely capture it.

Stop a Task

cella task stop <branch>

Aborts a running task (sends SIGTERM to the process tree).

Exit Codes

Code	Meaning
0	Success (done)
124	Timed out (timed_out)
130	Stopped by user (failed)
Non-zero	Command failed (failed)

Note: cella task list --json does not include an exit code field — it only reports status. To get the numeric exit code, use cella task wait <branch> (via $?).

Agent Dispatch Patterns

For headless agent dispatch across containers, cella task run wraps the agent CLI. Always include --timeout to prevent runaway agents.

Claude Code:

cella task run <branch> --timeout 300 -- claude --dangerously-skip-permissions -p "your prompt here"

--dangerously-skip-permissions is required for headless operation — without it Claude Code waits for interactive approval and the task stalls. The "no stdin data received in 3s" warning is cosmetic and does not block execution.

Codex:

cella task run <branch> --timeout 300 -- bash -c 'codex exec "your prompt here"'

Multi-word prompts must be wrapped in bash -c because cella task run shell-splits args after --. Without the wrapper, each word becomes a separate arg and Codex interprets them as a command name instead of a single prompt. Add --skip-git-repo-check if Codex doesn't recognize the worktree as a git repo.

Polling for Completion

# Poll all tasks
while cella task list --json | jq -e '.[] | select(.status == "running")' > /dev/null 2>&1; do
  sleep 10
done

# Or filter by specific branches to avoid blocking on unrelated tasks
while cella task list --json | jq -e '.[] | select(.branch == "feat/auth" or .branch == "feat/api") | select(.status == "running")' > /dev/null 2>&1; do
  sleep 10
done

Native Agent Features Inside Containers

Cella is the container isolation layer underneath native agent features. Native tools handle orchestration (spawning agents, coordinating work). Cella provides isolated environments, port de-confliction, Docker sandboxing, and lifecycle management.

Claude Code Subagents (Agent Tool)

Claude Code's Agent tool spawns subagents to work in parallel. When called with isolation: "worktree", the subagent gets its own git worktree inside the container for safe parallel file editing:

Agent({
  description: "Implement auth module",
  prompt: "Add JWT auth to src/auth/",
  isolation: "worktree"
})

These Claude-level worktrees are inside the container's filesystem — separate from cella's host-level worktrees:

• Cella worktrees: host-side, each with its own container (full environment isolation — different packages, ports, deps)
• Claude worktrees: in-container directory copies (lightweight — same packages, ports, deps, just separate file trees)

Both coexist. Use cella worktrees (cella branch) when you need full environment isolation. Use Claude worktrees (isolation: "worktree") when you need lightweight file-edit parallelism within a single container.

Claude Code Agent Teams

Agent teams let a team lead spawn teammates as independent Claude Code instances within the same container. They coordinate via shared files in the workspace.

Enabling: set the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 before starting Claude Code.

How it works inside cella:

• The team lead spawns teammates; each teammate is a separate Claude Code process
• Coordination uses file-based mechanisms: the team lead writes task descriptions to markdown files, teammates pick them up, and report results back via the same files
• All teammates share the same container — same packages, deps, environment, and mounted git repo
• The team lead orchestrates: assigns work, monitors progress, and collects results

When to use teams vs cella task run:

Use teams when...	Use cella task run when...
Agents need to coordinate on interrelated files	Agents work on independent features
Changes must stay in sync (e.g., API + client)	Each agent needs its own branch
Single environment is sufficient	Agents need separate deps/ports
You want native Claude Code orchestration	You want full container isolation

Limitation: all teammates must run in the same container. For cross-container agent work, dispatch each via cella task run in separate worktree containers.

Codex Inside Cella Containers

Subagents: Codex's native subagent system (capped at 6 concurrent threads) works inside cella containers. In the Codex CLI, use /agent to switch between active subagents. All subagents share the same container environment.

Cross-container Codex work: dispatch separate cella task run commands into different branch containers. Each gets its own worktree, container, and environment. This is how you parallelize Codex work with full isolation.

Configuration:

• Custom agents: place TOML config files in .codex/agents/ within the workspace
• Per-workspace instructions: use AGENTS.md at the repo root
• Git worktree recognition: add --skip-git-repo-check if Codex doesn't recognize the worktree directory

Bridge Pattern: Native Orchestration + Cella Isolation

┌─────────────────────────────────────────────────┐
│  Native orchestration layer                      │
│  (Claude Code teams/subagents, Codex threads)    │
│  Decides WHAT to do                              │
└───────────────────────┬─────────────────────────┘
                        │ spawns/coordinates
┌───────────────────────▼─────────────────────────┐
│  Cella container isolation layer                 │
│  (per-branch containers, port allocation,        │
│   env isolation, lifecycle management)           │
│  Provides WHERE to do it                         │
└─────────────────────────────────────────────────┘

• In-container parallelism: native subagents (Agent tool with isolation: "worktree", Codex /agent threads, team-agents) within a single container
• Cross-container parallelism: cella task run to dispatch agents in separate containers with full isolation
• Hybrid: native orchestration decides what to do; cella provides where to do it

Parallel Development Pattern

Decompose -> Dispatch -> Monitor -> Collect

1. Decompose — break the task into independent units. Each should be completable without changes to the other units and have a clear success criterion.

2. Dispatch — create branches and dispatch tasks:

cella task run feat/auth --timeout 300 -- claude --dangerously-skip-permissions -p "Add JWT auth middleware"
cella task run feat/rate-limit --timeout 300 -- claude --dangerously-skip-permissions -p "Add rate limiting"
cella task run feat/logging --timeout 300 -- claude --dangerously-skip-permissions -p "Add structured logging"

3. Monitor — check status:

cella task list

4. Collect — check results and verify:

cella task logs feat/auth
cella exec feat/auth -- cargo test -p middleware

Failure Handling

• One task's failure does NOT affect other running tasks
• Timed-out tasks: exit code 124, status timed_out
• Stopped tasks: exit code 130
• After failure: inspect logs (cella task logs <branch>), fix the issue, re-run the task (previous entry is replaced)

Performance Expectations

Operation	Typical Time
Branch creation	~80s (full container build)
Exec latency	Sub-second
Cross-container exec roundtrip	Sub-second
Claude Code task (simple)	20-30s
Codex task (simple)	10-15s

Troubleshooting

Symptom	Fix
"No daemon connection info"	Daemon not running on host. Ask the user to run cella up on the host
"Failed to connect to host daemon"	Run cella doctor for details; daemon may need restart on host
Exec to main fails	Fixed in v0.0.48+ — main container lookup uses workspace_path fallback
* marker shows wrong branch	Fixed in v0.0.48+ — uses CELLA_CONTAINER_NAME matching
JSON in human output	Mostly fixed in v0.0.48+ — rare JSON fragments may still appear during branch creation
down --rm fails with ContainerNotFound	Container was already removed. Use cella prune --missing-worktree to clean up the orphaned worktree entry
"bind source path does not exist" on branch creation	Transient race condition. Retry cella branch — typically succeeds on second attempt
Claude Code waits for approval	Add --dangerously-skip-permissions for headless execution
"no stdin data received in 3s"	Cosmetic Claude Code warning; task proceeds normally
Codex treats prompt as command name	Wrap in bash -c 'codex exec "prompt"'
Codex doesn't recognize git repo	Add --skip-git-repo-check flag
Packages missing in new container	Packages are per-container; install in each branch or use a shared base image
Agent can't reach API endpoints	Cella containers share the host network by default; check DNS/firewall
Agent teams can't communicate	All teammates must run in the same container, not across containers
Task shows "timed_out"	Increase --timeout or break the task into smaller pieces
task wait returns unexpected exit code after re-dispatch	If you re-dispatch a task on a branch that already had a completed/timed-out task, a concurrent task wait from the old dispatch may race with the replacement. Use cella task list --json to verify the current task status instead of relying solely on task wait exit codes
Plan/task files not visible in worktree	Place shared files in ~/.claude/plans/ — this volume is mounted in ALL containers. Don't rely on git-tracked files for cross-worktree sharing

Best Practices

• 3-4 parallel containers is the sweet spot for most repos and machines
• Always use --timeout on cella task run to prevent runaway agents
• Use isolation: "worktree" on Claude Code subagents to prevent file conflicts within a container
• Use cella task list --json for programmatic monitoring
• Use cella exec for quick verification after tasks complete
• Containers persist until explicitly removed with cella down --rm or cella prune
• File-based coordination works across containers because the git repo is shared via bind mount
• Use native team/subagent features for orchestration; cella handles isolation only