Agent Focus Documentation

Agent Focus works as a set of Claude Code skills. Install them using the Claude CLI:

claude skills add agent-focus

This installs:

• /af-begin - Start a worker session in a scope
• /af-handoff - Complete session with knowledge refinement
• /af-orch - Start orchestrator session for project coordination
• af CLI - Command-line tools for project management

1. Initialize your project

af init my-project
cd my-project

This creates:

• specification.md - Project specification with catalog numbers
• implementation-plan.yaml - Task breakdown with dependencies
• .agent-focus/ - Configuration directory

2. Start your first scope

/af-begin my-first-scope

The agent will load project context and begin session 01 with focused context.

3. Work and hand off

When approaching the token limit or completing a logical chunk:

/af-handoff

This compresses knowledge, updates handoff.md, and prepares for the next session.

4. Continue work

/af-begin my-first-scope

The new agent receives refined knowledge from your handoff and continues where you left off.

Focus persistence is the ability to maintain optimal attention across arbitrary timelines. For AI agents, this means staying within the 50-150k token "sweet spot" indefinitely.

Traditional approaches conflate memory (context window size) with focus (attention quality). A 1M token window doesn't provide more focus - it just means more information competing for attention.

Rather than front-loading all available context, Agent Focus uses progressive disclosure:

1. 1.
   Knowledge first - Compressed wisdom from previous sessions (~10-40k tokens)
2. 2.
   Session logs if needed - Work summaries from recent sessions
3. 3.
   Full transcripts only when necessary - Complete session history

This keeps initial context lean and focused on what matters.

Each handoff is an opportunity to compress and improve knowledge:

Like a relay race team vs. a marathon runner:

• Each agent performs at peak performance during their leg
• Handoff happens before fatigue sets in
• Knowledge is compressed and refined, not just passed
• The team maintains optimal pace indefinitely

Scopes are focused work contexts that can span multiple sessions:

project/
└── .agent-scopes/
    ├── auth-core/          # Scope
    │   ├── knowledge/
    │   │   └── handoff.md
    │   └── sessions/
    │       ├── 01...       # Session
    │       ├── 02...       # Session
    │       └── 03...       # Session
    └── api-layer/          # Scope
        └── sessions/
            └── 01...       # Session

Sessions are individual agent runs that stay under 150k tokens.

Start a worker session in a scope.

/af-begin scope-name

What it does:

• Loads project specification
• Reads handoff from previous session (if exists)
• Assembles focused context for the scope
• Starts new session with optimal token budget

Complete the current session with knowledge refinement.

/af-handoff

What it does:

• Compresses session knowledge
• Updates handoff.md with refined wisdom
• Logs work completed
• Prepares context for next session

Initialize a new Agent Focus project.

af init [project-name]

Options:

Check project and scope progress.

af status [scope-name]

Shows active scopes, session counts, recent work, and token usage.

Query specifications by catalog number.

af spec 2.1.1

Retrieves the specification item referenced by catalog number 2.1.1 from your specification.md.

Query a past agent session. Wake a dormant session to ask questions about decisions it made.

af wake session-04

Example conversation:

Create .agent-focus/config.yaml in your project:

project:
  name: my-project
  handoff_threshold: 150000  # tokens
  auto_commit: true

scopes:
  default_template: standard

messaging:
  enabled: true
  thread_retention: 30  # days

Each scope can have custom settings in .agent-scopes/scope-name/manifest.json:

{
  "scope": "auth-core",
  "created": "2025-01-15",
  "sessions": 7,
  "handoff_template": "engineering",
  "auto_refine": true
}