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 (Managed Runtime)

Automated mode uses the IAS managed local runtime to process a queue of jobs without human interaction. The runtime 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 runtime or full profile.
2. Install runtime dependencies: cd scripts/ias-runtime && npm ci
3. Create a run: ias new-run my-feature
4. Initialize the runtime queue: node scripts/ias-runtime/run.mjs init --latest
5. Enqueue a job:

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

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

Runtime state

All runtime state is stored in your repository under the run directory:

runtime/
  config.json          # Runtime 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 through your operating system settings and redirect output to a log. The command below is safe to run from Git Bash on Windows as well as bash-compatible shells on macOS and Linux:

LOG="${TMPDIR:-/tmp}/ias-runtime-$(date +%Y%m%d-%H%M%S).log"
echo "runtime log: $LOG"
node scripts/ias-runtime/run.mjs run-loop --latest >"$LOG" 2>&1

To monitor from a second terminal, run tail -f <printed-log-path>.

Safety features

• Bounded turns. Each job runs for a configurable timeout (default: 30 minutes). The runtime 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 runtime crashes, you can resume with recover and run-loop.
• File locks. Only one runtime 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 runtime or full profile
• Runtime dependencies installed (npm ci in scripts/ias-runtime/)
• An OpenAI API key (for Codex SDK)

Console-Managed Mode

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

How it works

1. Bootstrap IAS with the runtime or full profile.
2. Authenticate: ias auth login
3. Link your repo: ias repo link /path/to/repo
4. Start the local agent runtime: ias start
5. In the IAS Hub: 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 IAS Hub.

What runs locally

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

The local runtime handles different job types through one operator-facing process:

• Operational jobs -- install_ias, apply_decision, build_context, and related setup or context jobs.
• Managed work jobs -- work and pr_review, the primary implementation and review job types.

When you run ias start, the complete local runtime starts the required loops together. Use ias start --daemon for background mode.

Verifying the connection

After starting the agent, confirm it is connected:

1. Open the IAS Hub 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

• An IAS Hub account and workspace (see Create a Workspace)
• IAS bootstrapped with the runtime or full profile
• Authentication configured (ias auth login)
• Repository linked to the IAS Hub (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.

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 IAS Hub during the day. When you have a queue of approved work jobs, let the automated runtime process them overnight. Check the IAS Hub 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 IAS Hub (Console-managed).
2. Evening. Approve proposals and start the automated runtime for execution (Automated).
3. Morning. Review results in the IAS Hub. 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 runtime against a run that was created through the Console -- it processes the same jobs.
• Resume Console-managed execution after an interactive debugging session -- the IAS Hub 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

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

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

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

Console-managed mode

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

Jobs not being claimed. Confirm the repo mapping in your local agent config matches the repository record in the IAS Hub. Verify the agent has the required capabilities for the job type.