Execution Modes

IAS supports three execution modes. Each mode determines who initiates work, how agents receive instructions, and where results are tracked. You can run a single mode or combine all three within the same team and even the same repository.

At a Glance

Interactive Mode

In interactive mode you run a coding agent directly in your terminal. You provide prompts, see output in real time, and decide what happens at every step.

How it works

1. Bootstrap IAS into your repo using any profile (see Deploying IAS to a Repository).
2. Open a terminal in the repo root.
3. Launch your preferred agent -- for example claude (Claude Code) or codex (Codex CLI).
4. The agent reads from docs/ias/ for project context, process guidance, and templates.
5. You direct the agent, review changes, and commit when you are satisfied.

What the agent reads

When you launch an agent interactively, it picks up context from the IAS scaffold automatically:

• AGENTS.md / CLAUDE.md -- top-level operating protocol
• docs/ias/project-context.md -- project metadata and constraints
• docs/ias/context/base-goal.md -- the overarching project objective
• docs/ias/process/ -- run protocol and quality gates

You do not need to re-explain your project in every prompt. The scaffold carries the context forward.

When to choose interactive mode

• Learning IAS. See exactly what the agent does at each step and build intuition for the system.
• Debugging and investigation. Step through problems interactively and inspect state along the way.
• Quick, well-scoped tasks. One-off changes that do not need queuing or coordination.
• Recovery. Fix a stuck job, resolve a merge conflict, or manually inspect run state.

Setup requirements

Interactive mode has the lightest requirements:

• A supported agent CLI (Claude Code, Codex CLI, or Gemini CLI)
• IAS bootstrapped into the repository with any profile (terminal is sufficient)

No server, no daemon, no Console account.

Automated Mode (Hybrid Runner)

Automated mode uses the IAS hybrid runner to process a queue of jobs without human interaction. The runner reads jobs from a file-based queue, executes bounded agent turns via the Codex SDK, saves results, and enqueues follow-up work.

How it works

1. Bootstrap IAS with the hybrid or full profile.
2. Install runner dependencies: cd scripts/ias-runner && npm ci
3. Create a run: ias new-run my-feature
4. Initialize the runner: node scripts/ias-runner/run.mjs init --latest
5. Enqueue a job:

   node scripts/ias-runner/run.mjs enqueue --latest \
     --role orchestrator \
     --prompt "Analyze the codebase and propose next steps"

6. Start the loop: node scripts/ias-runner/run.mjs run-loop --latest
7. The runner claims jobs one at a time, executes them, commits results, and enqueues follow-ups until the queue is empty.

Runner state

All runner state is stored in your repository under docs/ias/runs/<run>/runner/:

runner/
  config.json          # Runner configuration
  state.json           # Current status
  queue/
    pending/           # Jobs waiting to be claimed
    running/           # Job currently executing
    done/              # Completed jobs
    failed/            # Failed jobs
  jobs/
    <job-id>/          # Per-job logs and artifacts

Because state lives in the repo, you get a full audit trail via Git history.

Queue commands

Running overnight

For long-running sessions, keep the machine awake and redirect output to a log:

LOG="/tmp/ias-runner-$(date +%Y%m%d-%H%M%S).log"
caffeinate -dimsu nohup node scripts/ias-runner/run.mjs run-loop --latest >"$LOG" 2>&1 &
tail -f "$LOG"

Safety features

• Bounded turns. Each job runs for a configurable timeout (default: 30 minutes). The runner will not execute indefinitely.
• Role-based sandboxing. Reviewer roles get read-only access; implementer roles get write access.
• State persistence. After every job, state is saved. If the runner crashes, you can resume with recover and run-loop.
• File locks. Only one runner instance can process a given run at a time.
• Automatic retry. Transient failures are retried with exponential backoff.

When to choose automated mode

• Overnight execution. Queue work before leaving and review results in the morning.
• Long task lists. Process many bounded tasks sequentially without manual intervention.
• Reproducible runs. Every step is logged and committed for auditability.

Setup requirements

• Node.js 18+
• IAS bootstrapped with the hybrid or full profile
• Runner dependencies installed (npm ci in scripts/ias-runner/)
• An OpenAI API key (for Codex SDK)

Console-Managed Mode

In Console-managed mode, the IAS Command Center coordinates work across repositories and team members. Jobs flow through a central queue. Local agents connect to the Command Center, claim jobs, execute them against your Git checkout, and report results back.

How it works

1. Bootstrap IAS with the control-plane or full profile.
2. Authenticate: ias auth login
3. Link your repo: ias repo link /path/to/repo
4. Start the local agent: ias agent start
5. In the Command Center: create goals, review proposals, and answer decision requests.
6. The local agent claims jobs from the queue, executes them against your repo, and reports evidence (commit SHAs, changed files, pull request URLs) back to the Command Center.

What runs locally

Even in Console-managed mode, all execution happens on your machine (or your CI server). The Command Center never touches your source code. It only stores metadata -- job definitions, status, evidence references, and coordination state.

Two local executors handle different job types:

• CLI worker (scripts/ias-worker) -- handles install_ias, apply_decision, build_context, and other operational jobs.
• Hybrid runner (scripts/ias-runner) -- handles work jobs (the primary implementation job type).

When you run ias agent start, both executors are started together. You can also start them individually with ias worker start and ias runner start.

Verifying the connection

After starting the agent, confirm it is connected:

1. Open the Command Center and navigate to the Agents page.
2. Your agent should appear with a recent heartbeat.
3. The top-right Agents indicator shows a non-zero count.

When to choose Console-managed mode

• Teams. Multiple people managing shared repositories with centralized visibility.
• Multi-repo coordination. Goals that span several codebases, coordinated from a single dashboard.
• Approval workflows. Intent review, readiness scoring, and proposal approval before any code is written.
• Human-in-the-loop at scale. The Inbox collects all decision requests in one place for efficient triage.

Setup requirements

• A Command Center account and workspace (see Create a Workspace)
• IAS bootstrapped with the control-plane or full profile
• Authentication configured (ias auth login)
• Repository linked to the Command Center (ias repo link)

Which Mode Should I Use?

Follow this decision tree:

1. Do you need real-time, step-by-step control over the agent? Yes -- use Interactive Mode.

2. Are you working as a team, across multiple repos, or need centralized approval workflows? Yes -- use Console-Managed Mode.

3. Are you working solo on a single repo and want hands-off execution? Yes -- use Automated Mode (Hybrid Runner).

If none of these clearly fits, start with Console-Managed Mode. It provides the most flexibility and you can always drop into interactive mode when needed.

Combining Modes

Modes are not mutually exclusive. They share the same repository state, so switching between them is seamless. A common pattern for teams:

Console + Interactive for debugging

Use Console-managed mode as your primary workflow. When a job fails or a decision request needs investigation, drop into interactive mode in your terminal to debug and resolve the issue. Once resolved, the Console picks up where it left off.

Console + Automated for overnight runs

Create goals and approve proposals through the Command Center during the day. When you have a queue of approved work jobs, let the automated runner process them overnight. Check the Command Center dashboard in the morning for results and any decision requests that came up.

All three for full coverage

1. Day. Create goals and review proposals in the Command Center (Console-managed).
2. Evening. Approve proposals and start the automated runner for execution (Automated).
3. Morning. Review results in the Command Center. Debug any failures interactively (Interactive).
4. Repeat.

Switching between modes on the same repo

Because all IAS state lives in the repository (docs/ias/), you can switch modes at any time:

• Stop the Console-managed agent and launch an interactive agent session -- it reads the same context.
• Start the automated runner against a run that was created through the Console -- it processes the same jobs.
• Resume Console-managed execution after an interactive debugging session -- the Command Center sees the commits you made.

No migration, no export/import, no data loss.

Troubleshooting

Interactive mode

Agent does not see IAS files. Confirm IAS is bootstrapped: ias preflight --fix. Check that AGENTS.md or CLAUDE.md exists at the repo root.

Agent CLI not authenticated. Run the agent CLI once (claude or codex) and complete the sign-in flow.

Automated mode

Runner will not start. Check your Node.js version (node --version -- need 18+). Install dependencies: cd scripts/ias-runner && npm ci.

Jobs stuck in "running". The runner may have crashed. Run node scripts/ias-runner/run.mjs recover --latest to move stuck jobs back to pending.

Queue not processing. Check status with node scripts/ias-runner/run.mjs status --latest and look for errors in the job logs.

Console-managed mode

Agent shows offline. Verify your ~/.ias/worker.json configuration, especially the Convex deployment URL and workspace slug. Check network connectivity.

Jobs not being claimed. Confirm the repo mapping in your worker config matches the repository record in the Command Center. Verify the agent has the required capabilities for the job type.