Sessions & Trees

A session is an AI conversation. Unlike a CLI where conversations scroll up and disappear, Agor sessions can branch — fork siblings, spawn children, or ask side questions — building a genealogy tree you can navigate, resume, and reason about.

Every session lives inside exactly one worktree. Multiple sessions on the same worktree share a filesystem but have independent conversations.

Worktree: "auth-feature"
└─ Session: "Build authentication system" (Claude)
   ├─ Fork: "Write tests for auth"               (Claude)
   ├─ Fork: "Build user profile that uses auth"  (Claude)
   ├─ Spawn: "Research OAuth2 best practices"    (Codex)
   │   └─ Spawn: "Evaluate PKCE vs implicit flow" (Gemini)
   └─ BTW:  "What's the version of node here?"   (ephemeral)

A coordinator session fanned out to eight parallel security-review children — each its own introspectable conversation.

Three ways to branch

Fork — copy the context, keep the conversation

A fork creates a sibling session with a copy of the parent’s conversation context at that moment. Same accumulated knowledge, but the two diverge from there.

Session: "Built user authentication feature"
├─ Fork: "Write comprehensive unit tests for auth"
├─ Fork: "Build user profile page that uses auth"
└─ Fork: "Generate API documentation"

Use forks when downstream work needs the same starting knowledge but different focus. (Currently Claude Code only — other SDKs don’t yet expose conversation copy.)

Spawn — delegate with fresh context

A spawn creates a child session with a fresh context window. The parent decides what context to pass via the spawn prompt; the child is a focused subagent.

Parent: "Build complete e-commerce checkout flow"
├─ Spawn: "Implement payment gateway integration"
├─ Spawn: "Build inventory validation service"
└─ Spawn: "Create order confirmation email templates"

Use spawns when the parent is orchestrating and you want children to do focused work without dragging in the parent’s full history.

BTW — ephemeral side question

A btw is an ephemeral fork that runs concurrently and auto-archives when done. The parent never blocks — the answer is delivered back as a message in the parent’s conversation.

The “btw” button (❓) sits next to the prompt input. Click it, type your question, and it runs in a separate ephemeral session. When it completes, the result is injected back into the parent.

For orchestrating agents, the same thing is exposed via agor_sessions_prompt with mode: "btw" — agents can ask peer sessions quick questions without breaking their flow.

BTW uses session forking under the hood, so it’s currently Claude-only. For tools without fork support (Codex, Gemini), use mode: "subsession" instead.

A btw question runs in an ephemeral fork; the answer is delivered back inline in the parent’s timeline.

Why genealogy matters

Linear conversations are lossy. When an agent goes down a wrong path, you either start over or live with the corrupted context.

Branched conversations are exploratory. Every fork/spawn is:

• Introspectable — Full conversation history kept on disk; click any node and read it.
• Composable — Fork from forks, spawn from spawns, build deep delegation trees.
• Multiplayer-friendly — Teammates see the tree on the worktree card and understand the exploration.
• Resumable — Prompt any session in the tree at any time, even after it “completed.”

The tree is rendered on the worktree card on the board, and in full detail in the session view.

Spawned subsessions with callbacks

Spawning is more than “start a child.” Subsessions in Agor have first-class callback semantics:

• Non-blocking — The parent stays responsive while children run. If a callback arrives while the parent is mid-prompt, it queues.
• Automatic reports — When a child completes, it sends a callback message to the parent: status, summary, tool usage count, optional final message.
• Persistent — Children don’t disappear after completing. You can prompt them again (“can you fix the tests you broke?”) or have them spawn their own children.
• Cross-tool — Spawn a Codex child from a Claude parent, or a Gemini child from a Codex parent. Pick the right tool per subtask.

Configuration options

When spawning, you can override:

• Agentic tool — Claude Code, Codex, Gemini, OpenCode
• Model — Use a different model than the parent
• Permissions — Stricter or looser approval requirements
• MCP servers — Different tool sets (Codex MCP support pending)
• Callback content — Include last message (default on), include original prompt (default off), extra formatting instructions

Comparison with Claude Code’s native subagents

If you’ve used Claude Code’s subagent feature, Agor’s subsessions go further:

Crucially, neither Codex, Gemini, nor OpenCode SDKs natively support spawning subsessions. Agor unlocks this for all supported agents.

Real patterns

Parallel test generation

Parent (Claude): "Generate unit tests for these 5 files in parallel"
  ├─ Spawn (Codex): "Write tests for src/auth/login.ts"
  ├─ Spawn (Codex): "Write tests for src/auth/oauth.ts"
  ├─ Spawn (Codex): "Write tests for src/auth/jwt.ts"
  ├─ Spawn (Codex): "Write tests for src/auth/session.ts"
  └─ Spawn (Codex): "Write tests for src/auth/refresh.ts"

Five callbacks stream in as each child finishes. The parent reviews quality, runs the test suite, and decides next steps. Five-way parallelism on independent files, no merge conflicts.

Cross-agent code review

Claude (implements feature)
  └─ Spawn Codex: "Review the implementation across these 6 files"
      └─ Callback: critical bug found at file:line

Different agent, fresh eyes. Codex isn’t defending its own implementation choices — it’s just looking at the code. Especially effective for security audits, validating cross-SDK consistency, and catching bugs before PR submission.

Hierarchical delegation

Session A (architect)
  ├─ Session B (backend dev)
  │   ├─ Session C (API implementation)
  │   └─ Session D (database schema)
  └─ Session E (frontend dev)
      └─ Session F (UI components)

Each level delegates to specialized agents. Each session has a focused context window with only what it needs.

Best practices

Keep prompts focused. Subsessions work best with specific, isolated tasks. “Update the JWT token validation logic” beats “fix the auth system.”

Mind the filesystem. Forks and spawns share the worktree’s filesystem. Independent edits = no conflict. Parallel edits to the same file = git conflict. Plan accordingly.

Use callbacks wisely. Include the last message for quick status updates. Include the original prompt only when context might be lost. Add extra instructions when you need a specific report format (“include line numbers for all changes”).

Post-prompt anytime. Subsessions persist after completion. “Can you add error handling to the code you wrote?” is a valid follow-up at any point.

Configuration on a session

A session has more knobs than a CLI invocation:

• Model — Switch model mid-session from the panel footer
• Effort (Claude) — low / medium / high / max reasoning depth
• Permissions — How tool calls are gated (auto-approve, supervised, manual)
• MCP servers — Which tool sets are attached
• Effort and 1M context — Models with [1m] enable extended context

All of this is changeable at any point — you don’t have to start a new session to dial things up or down.

Session Settings modal — model, effort, permissions, MCP, env vars, callbacks, all editable mid-session.

Related

• Worktrees — The container for sessions
• Agor MCP Server — How agents introspect and spawn each other programmatically
• Rich Chat UX — Token accounting, context window viz, tool blocks, queueing
• SDK Comparison — What each agent SDK supports