Aperture

August 4, 2026 ยท View on GitHub

Aperture

The attention surface for agent work.

npm aperture npm core license docs

Aperture demo

Aperture is the live attention surface for humans working with agents like Claude Code and OpenCode.

It keeps the agent work that needs you in one place, decides what should be now, what should wait until next, and what should stay ambient, and sends your answer back into the same loop.

Getting Started

There are three clean ways to start:

  • Use the product now
    • install @tomismeta/aperture
    • run aperture
    • connect Claude Code or OpenCode and use the TUI
  • Build with the SDK
    • install @tomismeta/aperture-core
    • embed ApertureCore in-process inside your own host, workflow, or UI
  • Review a captured session
    • use aperture --capture or pnpm session:export
    • prepare an offline-review artifact with pnpm session:review
    • inspect it through the Lab review loop

If you need to send external work into a running Aperture product instance, the optional local HTTP ingress path is documented in Host-Neutral Ingestion Contract.

Install The Product

Install the CLI/TUI product:

npm install -g @tomismeta/aperture

Launch Aperture:

aperture

If you use Claude Code, Aperture prepares Claude on first launch. Restart Claude Code after the first run and confirm /hooks loaded.

If you want OpenCode, run:

opencode serve --port 4096
opencode attach http://127.0.0.1:4096

Then launch Aperture:

aperture

Use The SDK

Package: @tomismeta/aperture-core

npm install @tomismeta/aperture-core

The SDK loop is intentionally small:

ApertureEvent in via core.publish(...) or SourceEvent in via core.publishSourceEvent(...) -> AttentionFrame / AttentionView out -> AttentionResponse in

See packages/core/README.md.

What You Get

With @tomismeta/aperture:

  • a local CLI/TUI product
  • one shared attention surface for Claude Code and OpenCode, plus opt-in experimental Codex support
  • now, next, and ambient lanes for human attention
  • approvals, follow-ups, failures, and blocked work in one place
  • doctor, config, debug, completion, and uninstall commands
  • replayable capture bundles for troubleshooting real sessions

With @tomismeta/aperture-core:

  • the deterministic judgment engine inside Aperture
  • a small public SDK loop
  • the advanced /semantic and /trace entrypoints for adapter and explanation consumers

The Loop

+-----------+    +-------------+    +-------------+    +-------------+    +-------------+
|  Arrive   | -> |  Translate  | -> |    Judge    | -> |    Show     | -> |   Respond   |
|  events   |    |    facts    |    |  attention  |    |   surface   |    |   action    |
+-----------+    +-------------+    +-------------+    +-------------+    +-------------+

agent hooks       explicit facts      does this         what the          operator decision
and server        from raw payloads   deserve           operator          carried back
events                                attention now?    actually sees     to the tool

If you only remember one thing, remember this:

agent events in -> attention surface out -> human response back

Current Integrations

Claude Code

  • tool-aware permission frames
  • post-tool failure awareness
  • non-blocking completion awareness
  • waiting and input-needed awareness
  • follow-up handoff when Claude ends a turn with a real question

OpenCode

  • permission approvals from the server and terminal path
  • structured question.asked prompts
  • lightweight awareness when OpenCode is blocked waiting for a human reply
  • fallback reply handling for follow-up text questions when supported by the server event stream

Codex (experimental)

  • product opt-in through aperture codex connect --global and aperture --codex
  • App Server supervision through pnpm codex:run and pnpm codex:start
  • stdio, websocket, and Unix-socket App Server transport paths from source
  • stock Codex CLI hooks for approvals, permission requests, and lifecycle awareness
  • end-to-end approval routing proven for supported request families
  • broader interruption coverage still depends on what Codex App Server externalizes as requests

Pi (experimental, source-only)

  • Pi extension-event mapping into Aperture SourceEvent
  • optional tool-call hold policy through the Aperture response loop
  • intentionally not wired into the published product launcher yet

Claude Code and OpenCode are the mainline live paths today. Codex is included as an opt-in experimental product path; Pi remains source-only.

Common Product Commands

aperture
aperture --capture
aperture doctor
aperture config
aperture debug
aperture completion zsh
aperture --version
aperture help
aperture help opencode
aperture help codex
aperture help uninstall

From Source

If you want to work on the repo directly:

git clone git@github.com:tomismeta/aperture.git
cd aperture
pnpm install
pnpm release:check

To launch the product from source:

pnpm aperture

Repo-level examples and capture-review quickstarts live in examples/README.md.

Package Boundaries