deer CLAUDE.md

deer

Unattended coding agent — runs Claude Code in sandboxed tmux sessions against git worktrees, with a TUI dashboard.

Monorepo Structure

Bun workspace monorepo with three packages:

• packages/shared/ — Shared utilities used by both deerbox and the TUI (private, never published)
• packages/deerbox/ — Core sandbox orchestration library (no TUI dependencies)
• Root (src/) — Ink/React TUI dashboard

deer/                          # workspace root
  package.json                 # "workspaces": ["packages/*"]
  src/                         # deer TUI source (imports from "@deer/shared")
  packages/
    shared/
      src/                     # shared utilities: constants, i18n, credentials, git/detect, git/finalize
      package.json             # name: "@deer/shared", private: true
      tsconfig.json
    deerbox/
      src/                     # core modules (agent, sandbox, config, etc.)
      package.json
      tsconfig.json

Stack

• Runtime: Bun (required — uses Bun.$, Bun.file, Bun.spawn, etc.)
• Language: TypeScript (ESM)
• UI: Ink + React (terminal TUI)
• Sandbox: Anthropic SRT (@anthropic-ai/sandbox-runtime) — bwrap on Linux, seatbelt on macOS
• Config: TOML via @iarna/toml

Commands

bun test          # run all tests
bun run dev       # run CLI from source (must be inside a git repo)
bun run build     # compile Linux x64 binary to dist/

Architecture

Each agent task:

1. deer TUI invokes deerbox as a subprocess (via src/deerbox.ts) — deerbox outputs JSON to stdout
2. deerbox (session.ts) prepares a sandboxed session: worktree → ecosystem detection → gitconfig → auth proxy → SRT command
3. deer TUI launches the prepared command in a tmux session (deer-<taskId>) via src/sandbox/index.ts
4. Finalizes by creating a GitHub PR and cleaning up

@deer/shared (shared utilities)

Private package — never published. Both deerbox and the TUI depend on it.

File	Purpose
packages/shared/src/index.ts	Barrel export for all shared APIs
packages/shared/src/constants.ts	Shared constants (HOME, DEFAULT_MODEL, BYPASS_DIALOG_*, MAX_DIFF_FOR_PR_METADATA, PR_METADATA_MODEL)
packages/shared/src/i18n.ts	Language detection, setLang/getLang/getPRLanguage/detectLang
packages/shared/src/credentials.ts	resolveCredentials() — OAuth/API key resolution from env/files/keychain
packages/shared/src/git/detect.ts	detectRepo() — git repo detection by walking up from a directory
packages/shared/src/git/finalize.ts	PR creation: createPullRequest, updatePullRequest, pushBranchUpdates, hasChanges