Run Modes

Infa CLI supports three distinct ways to run Claude Code sessions. Each mode suits a different workflow.

Copy link

Comparison

Copy link

1. Interactive session

The simplest mode. Spawns a single claude remote-control process and streams its output directly to your terminal. No HTTP server, no database, no branch management.

infa session start                  # uses current directory
infa session start ~/my-project     # or a specific path

The target directory must contain a .claude/ folder (i.e. be a Claude Code project).

◆  Claude Session
   Starting remote-control session for: /Users/you/my-project
◆  Press Ctrl+C to stop

Claude prints a session URL to stdout once ready. Press Ctrl+C to stop.

Copy link

2. Automated local run

Start the preview server first, then trigger a run via the HTTP API. Infa will create a git branch, write hooks to .claude/settings.local.json, and spawn Claude with the run's environment variables.

infa preview

curl -X POST http://localhost:7100/api/sessions/run \
  -H "Content-Type: application/json" \
  -d '{"repoPath": "/path/to/repo", "prompt": "Refactor the auth module"}'

curl http://localhost:7100/api/sessions

What happens internally:

1. A git branch is created: feat/run_{runId}
2. git checkout main && git pull is run first
3. Hooks are written to .claude/settings.local.json (see Hooks & Agents)
4. Claude is spawned with INFA_RUN_ID, INFA_RUN_TOKEN, and INFA_PAPER_ID set
5. Hooks are deleted when the session ends

Copy link

3. Remote / cloud run

The fully automated mode. A run is queued from the Infa web UI (or via the Supabase runs table), and the local CLI picks it up automatically via Supabase Realtime.

Requirements: authenticated + board connected + infa preview running.

Flow:

Infa web UI
    │  INSERT into runs (status='queued')
    ▼
Supabase Realtime
    │  fires postgres_changes event
    ▼
infa preview (local)
    │  receives the run + its run_configuration
    ├─ git checkout {base_branch} + git pull
    ├─ git create branch feat/run_{runId}
    ├─ write .claude/settings.local.json (hooks)
    └─ spawn claude remote-control
           env: INFA_RUN_ID, INFA_RUN_TOKEN, INFA_PAPER_ID

The CLI subscribes as soon as infa preview starts, as long as Supabase credentials and a valid auth token are available. Each incoming run is filtered by user_id — you only receive runs belonging to your account.

Run status updates (running → completed / failed / cancelled) are written back to the runs table in real time.

Copy link

Stopping a session

For sessions managed by the HTTP server (modes 2 and 3):

curl -X POST http://localhost:7100/api/sessions/stop \
  -H "Content-Type: application/json" \
  -d '{"repoPath": "/path/to/repo"}'

The server sends SIGINT first, then SIGKILL after 5 seconds if the process hasn't exited.

For interactive sessions (infa session start), press Ctrl+C.

Copy link

Next steps

• Hooks & Agents — what gets written to .claude/settings.local.json during automated runs
• CLI Reference