Hyperfocus

Hyperfocus is a portable Agent Skill and multi-agent orchestration plugin for sustained, bounded deep work. It keeps one high-value objective in focus while specialized roles externalize scope control, progress accounting, time awareness, skepticism, and deliberate completion.

The useful metaphor is intense focus with externalized executive control. Hyperfocus does not simulate ADHD and is not clinical guidance. It is an engineering workflow for agents, not a diagnostic or therapeutic tool.

Install with skills.sh

Install Hyperfocus directly with the skills CLI:

npx skills add fielc92/hyperfocus

What it provides

• One vendor-neutral skills/hyperfocus/SKILL.md built around the open Agent Skills directory shape.
• Native role definitions for Codex, Claude Code, and OpenCode, plus a generic runtime contract.
• Six roles: Anchor, Mapper, Diver, Pulse, Counterfocus, and Closer.
• An event-sourced Focus Journal that works across Git worktrees.
• Finite Focus Leases and explicit completion conditions.
• Provisional subagent commits with independent acceptance.
• Crash recovery, validation, status, resume, and sanitized export commands.
• Static conformance tests and dynamic pressure-scenario fixtures.
• No runtime Python dependencies beyond Python 3.11 or newer.

Why the journal matters

Git records coherent repository changes. It does not reliably represent research, rejected hypotheses, budget decisions, active leases, or read-only subagent work. Hyperfocus therefore treats the Focus Journal as authoritative and uses commits only for repository milestones.

Every worker appends immutable, one-event-per-file journal entries. The Anchor derives snapshot.json and summary.md; workers never edit shared derived state. This makes parallel work auditable without forcing empty commits or allowing concurrent agents to overwrite one progress file.

Architecture

Role	Responsibility
Anchor	Owns the Focus Contract, budget, dispatch, journal folding, checkpoint acceptance, and final release. Only this role may dispatch subagents.
Mapper	Produces at most five bounded candidate threads without performing the full investigation.
Diver	Executes one Focus Lease and returns evidence, artifacts, verification, and a compact result packet.
Pulse	Independently decides whether to continue, switch, park, or stop.
Counterfocus	Attempts to falsify the leading conclusion and expose premature closure.
Closer	Reconciles accepted evidence into the requested deliverable and deliberately releases the run.

The state machine is:

INTAKE -> CONTRACT -> MAP -> LOCK -> DIVE -> PULSE
       -> COUNTERFOCUS -> SYNTHESIZE -> RELEASE

Package layout

hyperfocus/
├── skills/hyperfocus/          # Canonical Agent Skill, schemas, references, CLI
├── agents/                     # Claude Code plugin agents / generic prompts
├── commands/                   # Claude Code plugin commands
├── adapters/codex/             # Codex custom-agent TOML files
├── adapters/opencode/          # OpenCode agents and commands
├── adapters/generic/           # Capability-based runtime interface
├── .codex-plugin/plugin.json
├── .claude-plugin/plugin.json
├── evals/                      # Fresh-context behavioral pressure scenarios
├── examples/
├── tests/
└── install.py

Installation

The installer changes only Hyperfocus-owned paths. copy mode creates independent files; symlink mode points installations at the canonical package, which is convenient during development.

Replace /path/to/project with the target project root.

Codex

python install.py --runtime codex --scope project --target /path/to/project --mode copy

Installs:

.agents/skills/hyperfocus/
.codex/agents/hyperfocus-*.toml
.codex/config.toml

The installer preserves existing Codex configuration and adds only missing conservative defaults:

[agents]
max_threads = 6
max_depth = 1

Claude Code

python install.py --runtime claude --scope project --target /path/to/project --mode copy

Installs:

.claude/skills/hyperfocus/
.claude/agents/hyperfocus-*.md
.claude/commands/hyperfocus*.md

The repository can also be packaged directly as a Claude Code plugin because it includes .claude-plugin/plugin.json, root skills/, agents/, and commands/ directories.

OpenCode

python install.py --runtime opencode --scope project --target /path/to/project --mode copy

Installs:

.agents/skills/hyperfocus/
.opencode/agents/hyperfocus-*.md
.opencode/commands/hyperfocus*.md

OpenCode commands run the Anchor in the foreground. The Anchor may use the task tool only for Mapper, Diver, Pulse, Counterfocus, and Closer workers; every worker explicitly denies it. Read-only workers also deny edits.

Generic Agent Skills host

python install.py --runtime generic --scope project --target /path/to/project --mode copy

Installs the canonical skill under skills/hyperfocus, the portable role prompts under agents, and commands under commands. Hosts with different discovery paths can point their skill loader directly at skills/hyperfocus/SKILL.md and use adapters/generic/runtime-interface.md.

User-level installation

Pass the user configuration root as --target and use --scope user:

python install.py --runtime codex --scope user --target "$HOME" --mode copy
python install.py --runtime claude --scope user --target "$HOME" --mode copy
python install.py --runtime opencode --scope user --target "$HOME" --mode copy

Development symlinks

python install.py --runtime codex --scope project --target /path/to/project --mode symlink

Re-running an install is idempotent. The installer replaces only named Hyperfocus files and the hyperfocus skill directory; it does not delete unrelated agents, commands, or configuration.

Quick start

The host-facing /hyperfocus command is the normal entry point. The CLI below provides durable state and is also usable from any generic host.

Set a convenient command variable from the package root:

HF="python skills/hyperfocus/scripts/hyperfocus.py"

1. Create the Focus Contract

RUN_ID="$($HF init \
  --root . \
  --objective "Identify and verify the cause of intermittent checkout failures" \
  --mode debug \
  --done "Reproduce the failure from a clean checkout" \
  --done "Support the causal mechanism with controlled evidence" \
  --done "Verify a regression fix" \
  --constraint "Do not write to production" \
  --exclude "Unrelated checkout UI redesign" \
  --cycles 8 \
  --parallel 3)"

echo "$RUN_ID"

The contract fixes one objective, observable completion conditions, hard boundaries, exclusions, a finite budget, evidence standard, and extension policy.

2. Issue a bounded Focus Lease

$HF lease issue \
  --root . --run "$RUN_ID" \
  --id lease-retry \
  --thread retry-idempotency \
  --question "Can timeout recovery bypass the idempotency lookup?" \
  --deliverable "Finding with evidence, confidence, contradictions, and next action" \
  --owner diver-01 \
  --cycles 2 \
  --stop "The hypothesis is supported or falsified" \
  --stop "One renewal yields no new evidence"

Only the Anchor issues leases. Native hosts dispatch the corresponding Diver with the run ID, relevant completion condition, allowed tools, and write scope.

3. Record evidence and a result packet

$HF evidence \
  --root . --run "$RUN_ID" \
  --actor diver-01 --lease lease-retry \
  --claim "Recovery bypasses the initial idempotency lookup" \
  --ref "artifact:reproduction.log" \
  --strength strong

$HF result \
  --root . --run "$RUN_ID" \
  --id retry-result \
  --agent diver-01 \
  --lease lease-retry \
  --conclusion "The timeout recovery path bypasses the lookup" \
  --evidence "artifact:reproduction.log:strong" \
  --confidence 0.84 \
  --assumption "The simulator matches provider retry ordering" \
  --unresolved "Two simultaneous provider callbacks" \
  --recommendation continue

Result packets contain conclusions and evidence, not hidden reasoning or chain-of-thought transcripts.

4. Complete the lease and run Pulse

$HF lease complete \
  --root . --run "$RUN_ID" \
  --id lease-retry \
  --reason "Question answered with controlled reproduction"

$HF cycle --root . --run "$RUN_ID" --count 2

$HF pulse \
  --root . --run "$RUN_ID" \
  --decision switch \
  --reason "The causal path is supported; verification of the fix is now highest value" \
  --next-thread "Run the regression fix under concurrent timeouts"

Pulse is mandatory after two cycles, at budget thresholds, after material hypothesis changes, and before an extension.

5. Track a provisional subagent checkpoint

A code-changing Diver works in an isolated branch or worktree when the host supports it. After focused verification, the commit should be coherent and include trailers:

hf(checkout-retry/diver-02): enforce idempotency during recovery

Hyperfocus-Run: 01JZHF4ZJ87A6P3B5K0QX9M1YT
Hyperfocus-Agent: diver-02
Hyperfocus-Lease: lease-fix
Hyperfocus-Status: provisional
Hyperfocus-Verification: pytest tests/checkout/test_retry.py

Record the current commit:

$HF checkpoint \
  --root . --run "$RUN_ID" \
  --actor diver-02 \
  --lease lease-fix \
  --verification-command "pytest tests/checkout/test_retry.py -q" \
  --verification-exit-code 0

The commit remains provisional. After independent verification, the Anchor accepts it:

$HF checkpoint-decision accept \
  --root . --run "$RUN_ID" \
  --source-commit abc123 \
  --integrated-commit def456 \
  --verified-by verifier-01 \
  --verified-by counterfocus-01

A Diver never accepts or integrates its own checkpoint.

6. Update completion conditions

$HF condition \
  --root . --run "$RUN_ID" \
  --id done-1 \
  --status verified \
  --evidence artifact:reproduction.log

$HF condition \
  --root . --run "$RUN_ID" \
  --id done-2 \
  --status verified \
  --evidence result:retry-result \
  --confidence 0.91

status distinguishes pending, in-progress, supported, satisfied, verified, and blocked work. Do not call a condition verified merely because a plausible answer exists.

7. Inspect status

$HF status --root . --run "$RUN_ID"
$HF status --root . --run "$RUN_ID" --json

Status is rebuilt from immutable events rather than inferred from chat history or Git log.

8. Counterfocus and close

Before closing high-stakes or assumption-sensitive work, dispatch Counterfocus with the leading conclusion, strongest evidence, material assumptions, and conditions. Resolve or record any blocking challenge.

After every required condition is verified:

$HF close \
  --root . --run "$RUN_ID" \
  --conclusion "Timeout recovery bypassed the initial idempotency lookup; the verified fix restores it" \
  --confidence 0.93

Closing records unresolved risks and deliberately releases attention. The run must not continue merely because cycles remain.

State, recovery, and export

State locations

For Git repositories, runs live at:

<git-common-dir>/hyperfocus/runs/<run-id>

Using the Git common directory means linked worktrees see the same journal.

For non-Git projects, runs live at:

<project>/.hyperfocus/runs/<run-id>

The run layout is:

<run-id>/
├── contract.json
├── snapshot.json          # disposable derived view
├── summary.md             # disposable derived view
├── events/                # immutable, one JSON file per event
├── leases/
├── results/
├── artifacts/
└── locks/                 # local coordination; excluded from exports

Resume after interruption

$HF validate --root . --run "$RUN_ID"
$HF resume --root . --run "$RUN_ID" --interrupt-active
$HF status --root . --run "$RUN_ID"

Validation rejects malformed or renamed immutable events. Resume rebuilds corrupted derived state, marks vanished workers interrupted when requested, and expects a Pulse before new dispatch.

Sanitized export

$HF export \
  --root . --run "$RUN_ID" \
  --output "hyperfocus-$RUN_ID.zip"

A sanitized export recursively redacts JSON keys associated with tokens, passwords, secrets, credentials, private scratchpads, transcripts, and hidden reasoning. It excludes locks. Do not archive a raw run directory when sharing state.

CLI reference

hyperfocus init                  Create a Focus Contract and run
hyperfocus event                 Append a generic immutable event
hyperfocus condition             Update evidence state for a completion condition
hyperfocus lease issue           Issue one bounded Focus Lease
hyperfocus lease complete        Mark a lease complete
hyperfocus lease park            Park a lease without losing it
hyperfocus lease interrupt       Mark an orphaned lease interrupted
hyperfocus lease cancel          Cancel invalid or duplicate work
hyperfocus evidence              Record claim-linked evidence
hyperfocus hypothesis            Record a hypothesis state
hyperfocus result                Store a result packet
hyperfocus pulse                 Record continue/switch/park/stop
hyperfocus cycle                 Consume investigation cycles
hyperfocus extend                Record an approved extension
hyperfocus park                  Add a tangent to the parking lot
hyperfocus risk                  Record a risk and mitigation
hyperfocus checkpoint            Record a provisional Git checkpoint
hyperfocus checkpoint-decision   Accept or reject a checkpoint
hyperfocus fold                  Rebuild snapshot and summary
hyperfocus status                Show evidence-derived progress
hyperfocus validate              Validate a run or the package
hyperfocus resume                Recover an interrupted run
hyperfocus export                Create a sanitized run archive
hyperfocus close                 Deliberately release a completed run
hyperfocus install               Install the package for a runtime

Run python skills/hyperfocus/scripts/hyperfocus.py COMMAND --help for exact arguments.

Capability degradation

Hyperfocus preserves the same contracts across hosts:

Host capability	Behavior
Parallel subagents	Run at most three independent leases concurrently.
Sequential subagents	Run independent leases one at a time in separate contexts.
No subagents	Emulate each role as a labeled isolated pass in the foreground agent.
Git and worktrees	Isolate code-changing Divers in worktrees or native equivalents.
Git without worktrees	Use non-overlapping file scopes or patch-only output.
No Git	Journal evidence and artifacts; omit commit checkpoints.
No atomic file creation	Serialize event writes through the Anchor.

Agent depth remains one. Workers never receive delegation permission.

Safety and privacy

• Never persist API keys, tokens, passwords, credentials, raw environment values, hidden reasoning, or private scratchpads.
• Result packets store conclusions, evidence, assumptions, contradictions, and uncertainty—not chain-of-thought.
• The installer changes only Hyperfocus-owned paths.
• export validates and sanitizes state before sharing.
• Local state is not pushed automatically.
• A future remote state branch should remain opt-in and contain only sanitized material.
• High-stakes work requires an independent Counterfocus challenge and the evidence standard named in the contract.

Behavioral evaluation

evals/hyperfocus-pressure.yaml contains seven fresh-context scenarios that tempt:

• unbounded rabbit holes;
• duplicate parallel agents;
• recursive delegation;
• silent budget extensions;
• premature closure;
• commit spam and self-acceptance;
• using Git as the sole progress database.

Follow evals/README.md: run each scenario once without the skill and once with it in fresh model contexts, preserve visible outputs, and score manually. Static tests cannot prove behavioral compliance, and the evaluation never requests hidden reasoning.

Development and verification

pytest -q
python -m compileall -q skills/hyperfocus/scripts
python skills/hyperfocus/scripts/hyperfocus.py validate --package .

Smoke-test all installers in disposable directories:

python install.py --runtime codex --scope project --target /tmp/hf-codex --mode copy
python install.py --runtime claude --scope project --target /tmp/hf-claude --mode copy
python install.py --runtime opencode --scope project --target /tmp/hf-opencode --mode copy
python install.py --runtime generic --scope project --target /tmp/hf-generic --mode copy

The implementation and design records are under docs/superpowers/.

License

MIT. See LICENSE.