Skip to main content
An agent in Pentagon is a managed Claude Code process. Each agent appears as a desk on the Office Canvas, runs in its own terminal session, and operates on a specific project directory.

​
Agent Lifecycle

Spawn → Active / Ready / Needs Input → Dormant → Delete
  1. Spawn — Click an empty grid cell or press Cmd + N. Choose a directory, name, model, and permissions.
  2. Active — The agent is running tool calls or generating a response.
  3. Ready — The agent is idle, waiting for your next prompt.
  4. Needs Input — Claude has finished its turn and is ready for follow-up.
  5. Dormant — The process has been paused. The session is preserved but not running.
  6. Delete — Select the desk and press Delete. The process is killed and the agent is removed.
You can respawn an agent at any time through its context menu. This kills the current process and starts a fresh session while preserving the agent’s identity files.

​
Status States

Each agent desk displays a colored ring indicating its current state.
StatusLabelRing ColorHexDescription
idleReadyGreen#4ADE80Waiting for your input
activeActiveYellow#FBBF24Working — tool calls in progress
waitingInputNeeds InputGreen#4ADE80Finished its turn, ready for your next prompt
dormantDormantGray—Paused — session preserved but not running
errorErrorRed#F87171Something went wrong

​
Git Worktree Isolation

Pentagon uses git worktrees to keep agents from stepping on each other’s changes.
  • First agent in a repo — works on your existing branch. No worktree is created.
  • Additional agents in the same repo — each gets its own git worktree with an isolated branch. Changes stay separate until you merge.
This means you can run multiple agents against the same codebase simultaneously without conflicts.

​
Agent Identity Files

Each agent has a set of identity files stored in its working directory under .pentagon/. These files define who the agent is, what it should do, and what it remembers.
FilePurposeLearn More
SOUL.mdRole, personality, instructions, constraintsSouls
TASKS.mdMarkdown checklist of current work itemsTasks
MEMORY.mdPersistent notes and context across restartsMemory
heartbeat-config.jsonRestart behavior and schedulingHeartbeat
report.jsonAgent self-reported status (read-only)—
These files are injected into the agent’s Claude Code system prompt via hooks. Edit them through the Detail Panel tabs or directly on disk — changes are picked up on the next session or respawn.

​
Cloning

Adjacent to each agent desk, + indicators appear on empty grid cells. Click one to clone that agent — Pentagon creates a new agent with the same project directory, automatically isolated in its own git worktree.