Interactive sessions

`xc i` boots an interactive coding-agent session with all of xCoder's hooks, skills, and flow guards live. The agent itself is unchanged — the constraint layer wraps around it.

Basic use

bash
cd ~/code/your-project
xc i                                # start a session in the current repo
xc i "implement OAuth login"        # with an initial prompt
xc i --skill ui                     # explicit skill (skips auto-detect)

What happens on boot

  • xc boot runs as a SessionStart hook — the agent receives a fresh orientation block (recent merges, open PRs, active branches, fresh specs) plus the flow-discipline framing.
  • PreToolUse hooks become live: no-edit-on-integration on every edit/commit, typecheck-must-pass-before-commit on every commit, commit-must-reference-issue on every commit message.
  • Stop hook becomes live: session-end-pr-backstop fires when the agent ends with commits ahead of integration but no PR.
  • Skills (auto-detected from the repo) inject system prompts — ui, backend, devops, testing, pr-iteration, etc.

Choosing the agent runtime

xCoder wraps several coding-agent runtimes. The default is whichever you have installed; you can pin a specific one with xc mode:

RuntimeMode idNotes
Claude Codeclaude-codeDefault. Best hook integration today.
CursorcursorHeadless mode via composer-run; partial hook integration.
CodexcodexOpenAI Codex CLI.
OpenCodeopencodeopen-source Claude alternative; settings.json-based hooks.
ZedzedZed AI assistant; experimental driver.
bash
xc modes                     # list available runtimes
xc mode <agent-id> codex     # pin a specific agent to Codex

Watching from another terminal

While your session runs, you can watch the FlowEngine's view of the world from another terminal:

bash
xc flow status
xc flow events --type flow.transition
xc flow events --type flow.bypass
xc autopilot status      # if you also have autopilot running

Bypassing a guard mid-session

Sometimes you genuinely need to override. xCoder makes that explicit:

Three explicit override paths

  • XCODER_ALLOW_INTEGRATION_EDIT=1 git ... — single shell invocation; right for hotfixes.
  • XCODER_SKIP_QA_GATE=1 git commit ... — single shell invocation; right for WIP commits.
  • xc flow override I-N --reason "..." — recorded for the active task; emits flow.bypass.

When the session ends

The Stop hook fires. If you've finished real work but forgot to push and open a PR, you'll see this in stderr:

text
xCoder backstop notice — branch `feat/widget` has 3 commits ahead of `main` but no open PR.

Open a PR to ship this work:
  gh pr create --fill --base main

Or set XCODER_AUTO_PR=1 to have the backstop auto-open future PRs.

Next

Autopilot →

Continuous autonomous loop instead of interactive.

Hooks →

What each hook does and how to bypass on purpose.

PR iteration →

The xc pr playbook — agentic merge work.