Delegate with clear criteria
Start a dedicated session or take over existing work after resolving its exact session ID.
Agent skill / requires goals-iterm-mcp / MIT
Delegate the work.
Stay with it
until it is done.
Give a coordinating agent a repeatable workflow for directing coding CLIs in iTerm2: inspect progress, make routine decisions, recover stopped work, and verify results.
Workflow / illustration
Task → Claude Code / iTerm2
Diagnose. Fix. Run relevant tests.
Observe → Decide → Continue
Check state before sending instructions.
Verify → Record → Finish
Changes, evidence, and an audit trail.
Your task → Coordinating agent + skill → iTerm2 via MCP → Coding CLI
A workflow built around your terminals.
Monitor before intervening
Inspect progress after instructions. Avoid duplicate dispatches and recover only after confirming work has stopped.
Leave a reviewable record
Keep a Markdown audit ledger of instructions, feedback, decisions, delivery, and acceptance evidence.
Setup
Connect. Then coordinate.
Install the terminal connection first. The skill provides the workflow; the MCP server provides the tools.
- Connect goals-iterm-mcp
On your Mac, enable the iTerm2 Python API and configure the local MCP server in the coordinating agent’s client. Verify tool discovery and list_sessions.
- Prepare the execution CLI
Install and authenticate Claude Code, Codex CLI, or your chosen CLI in iTerm2. Confirm it works in a new terminal tab.
- Install the whole skill package
Use your client’s supported skill mechanism. Keep SKILL.md, references/, and agents/ together under goals-iterm-skill, then reload skills as the client requires.
- Set the task and acceptance criteria
Name the project and CLI, define observable completion criteria, and ask the agent to use goals-iterm-skill. Start with the example below.
Continuous monitoring needs host scheduling or wakeups, or polling during an active agent run. The skill does not provide a background service and cannot keep monitoring after the run ends without a wakeup mechanism.
Example prompt
Make the handoff explicit.
Use goals-iterm-skill to have Claude Code in iTerm fix the login issue in
/path/to/project. Diagnose first, then fix it and run only relevant tests.
Monitor after every instruction, make routine technical decisions, and recover
from network failures only when the task has stopped and will not resume itself.
After acceptance checks pass, stop monitoring and summarize changes, tests,
and remaining issues. Do not publish.Before you begin.
Does installing the skill install MCP too?
No. Connect goals-iterm-mcp separately in the coordinating client. Installing the skill alone does not expose terminal tools.
Can it take over an existing CLI session?
Yes. It first resolves the exact session ID and checks whether work is already running, so it can continue monitoring without duplicating the task.
What goes into the audit ledger?
Instructions, CLI feedback, decisions and their basis, delivery results, recovery, acceptance evidence, and cleanup. Entries include timestamps and linked event IDs. The ledger is an operational record, not a full terminal recording.
Do I need a Goal feature?
No. A supported host’s Goal feature can track a multi-step objective, but the workflow can also be used without it. A Goal does not replace a monitor or supply background wakeups.