Skip to content
Raed2180416Public

About

Re-ground coding agents in the original prompt, complete context, and current repository

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

/zoomout

Keep working in the same chat. Re-ground before the quality falls off a cliff.

Long coding-agent sessions have a predictable failure mode: the agent starts with the right task, gets buried in tools and compacted context, then quietly optimizes for a tiny local problem instead of the thing you originally asked for.

/zoomout is the reset button for that moment.

You invoke it in the chat you are already using. Zoomout goes back to the original request, recovers the available conversation, rereads the current repository from disk, checks Git state, and gives the agent a compact evidence packet to inspect before continuing.

You do not need to abandon the chat and start over. The goal is to keep the same working session while reducing the quality loss caused by memory drift, context compaction, tunnel vision, and local happy paths. It reduces that risk; it cannot guarantee perfect reasoning or task completion.

The experience

You keep working normally
          │
          ├── type /zoomout when you want a reset
          │       or let your selected mode trigger it
          ▼
Zoomout reads the source of truth again
  • protected first prompt
  • complete provider transcript, when available
  • complete eligible repository
  • instructions and configuration
  • Git status and changed files
          │
          ▼
The agent continues in the same chat, grounded in current evidence

Quick start

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .

# One-time provider adapter generation
zoomout install claude --project .

# Choose how much automation you want
zoomout configure --project . --mode manual

# Immediate manual checkpoint
zoomout capture --project . --task "Your original requested task"

The generated adapter is a reviewable template under .zoomout/integrations/<provider>. Copy it into the provider’s supported hook location according to docs/compatibility.md; Zoomout does not silently overwrite your existing configuration.

Three ways to use it

zoomout configure --project . --mode manual      # only explicit /zoomout
zoomout configure --project . --mode compaction  # after every post-compaction event
zoomout configure --project . --mode auto        # detect likely tunneling

manual is the default and most predictable mode.

compaction runs after a confirmed post-compaction lifecycle event, so the agent gets re-grounded immediately after its context has been compressed.

auto watches for converging signs of tunneling: user corrections, repeated tool/action signatures, repeated errors, and long runs without explicit verification. It requires multiple signal categories, uses a cooldown, and records why it fired. It is a detector of risk—not a claim that the model is definitively wrong.

Set ZOOMOUT_MODE to override the project setting for one process.

What gets created

Each checkpoint lives under .zoomout/sessions/<id>/grounding/:

Artifact Purpose
grounding.md Human-readable briefing for the next model step
grounding.json Machine-readable evidence packet
chat-history.snapshot Byte-for-byte transcript copy when a provider transcript is available
../events.jsonl Local hook-event audit trail

The repository scan reads and hashes every eligible file, while excluding dependency, generated, and cache directories. Important instruction files are also excerpted so stale local rules become visible.

If a provider does not expose its full transcript, Zoomout says so plainly. It never presents its own hook log as a complete chat history.

Ten initial integrations

Claude Code, OpenAI Codex CLI, OpenCode, Gemini CLI, Cursor Agent CLI, GitHub Copilot CLI, Cline, Goose, Aider, and Windsurf Cascade.

See the compatibility matrix for current lifecycle surfaces, platform notes, and integration limitations.

Important boundary

Zoomout can prove that it reread and packaged current evidence. It cannot prove that an agent understood every file or completed the task correctly. The checkpoint tells the agent what to read, what changed, and where contradictions may exist; the agent still has to do the thinking.

Test

python -m pytest -q

About

Re-ground coding agents in the original prompt, complete context, and current repository

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages