What separates a good session from a frustrating one is mostly knowing how
input reaches the agent and when the agent is allowed to act. That is this
page.
The object model
- A session is one agent process inside a workspace.
- A chat thread is the durable conversation. Threads outlive processes: kill
the session, restart the app, reconnect from another machine — the thread and
its transcript are still there, because
archcar owns them, not the UI.
- A turn is everything the agent does between one of your messages and the
next. One tool call is not a turn.
Several sessions in one workspace is normal and share the branch on purpose.
Several workspaces is how you keep work independently reviewable. Do not reach
for a second workspace when what you want is a second chat.
Which agents actually run
Starting a session
Options at launch: --model, --plan-mode, --fast-mode, --approval-mode,
--reasoning-mode, --effort-mode, and for Codex --codex-personality,
--codex-goals, --codex-skills. They are passed through to the harness, so
the accepted values are the provider’s, not Archductor’s.
session open prints or runs the equivalent command for an external terminal
instead of a managed session — useful when you want the agent’s own TUI.
Queueing versus steering
This is the part worth internalising.
Messages go into a durable input queue owned by the daemon. They are not
typed into a terminal. Consequences:
- A message survives the app closing, the daemon restarting, and you switching
machines.
- It is delivered when the agent is ready for it, not into the middle of a
running turn — so you can queue three follow-ups while the agent works and
they arrive in order, each as its own turn.
Steering is the opposite: deliver now, into the turn in flight.
In the app that is mod+enter. Use it to redirect an agent that has gone the
wrong way; use the normal queue for everything else. Interrupting a good turn
to add a nice-to-have wastes the turn.
archductor archcar interrupt <session-id> stops the turn without sending
anything.
Input kinds — user, review-prompt, control-command, raw-terminal —
control how the input is framed. You rarely set them by hand; the app uses them
when staging a review comment or a failing check into a session, which is the
feature that replaces copy-pasting diffs into chat.
Permission prompts
When an agent asks to do something that needs approval, the request becomes an
interaction the daemon holds. It does not block on a TUI you have to be looking
at.
--always records the approval so the same request is not asked again.
deny --message is the useful form: the message reaches the agent, so it can
choose a different approach rather than just failing.
Plan mode
Plan mode puts a chat into research-and-propose instead of build. You get a
plan to read before any file is written.
In the app: mod+shift+tab to toggle, mod+shift+enter to approve. Worth using
by default for anything touching more than a couple of files — reading a plan
is much cheaper than reading a diff you then have to reject.
Plans the agent saves live under the workspace’s .context/plans/ and are
listed by archductor archcar context-plans <workspace>.
Mid-session controls
Switching model mid-thread is the common one: start cheap, escalate when the
agent is clearly out of its depth, without losing the conversation.
Keeping track of who did what
With several sessions in one workspace, “which agent wrote this” stops being
obvious. The daemon tracks it.
A snapshot writes a durable patch under
.context/archductor/contributions/, records the commands the daemon ran, and
keeps any risks or blockers you attach. Those risks then appear in the
generated PR body, which is the point — the person reviewing should not have to
excavate them from chat.
Tasks and summaries are the same idea at workspace scale:
context-briefing is the one to hand a fresh agent that is picking up someone
else’s workspace.
Background tasks
Fire-and-forget: create the workspace, run the agent, run the checks, write the
summary, optionally open the PR — without you watching.
A supervisor thread ticks every 10 seconds and moves the task through
pending → running → checking → summarizing → opening_pr → ready, or to
failed / cancelled. Liveness comes from real session state, not from
guessing at terminal output. The desktop shows an OS notification on
ready and failed.
--agent provider[=prompt] (repeatable) runs additional agents in the same
workspace, each with its own session and optionally its own prompt. All of them
link to the workspace task, so per-agent provenance still works.
Background tasks run Codex and Claude only. A shell has no idle signal, so
there is nothing to advance the task on.
--no-checks skips the repository’s configured checks. --open-pr opens a
draft; add --ready-pr for ready-for-review.
MCP
Archductor is an MCP server, so an agent can query and drive Archductor itself.
Two profiles, for two different jobs:
full — an external client driving Archductor: workspaces, tasks,
sessions, prompts, summaries, context, changes and diffs, checks, review
status, PR draft and create, background tasks.session — what an agent needs to keep its own workspace context
current, and nothing else: set_workspace_context, get_context_briefing,
get_summary, list_tasks, create_task, update_task. This is the right
default for mcp register, because an agent that can archive its own
workspace is a hazard, not a feature.
Because the tools are archcar requests, an MCP client can drive a remote
daemon by pointing it at one — see
Running on a server.
The server deliberately exposes no presentation state. Layouts, panel
positions, and theme are not MCP tools.
Skills and MCP servers across agents
Different agents keep skills and MCP servers in different places, so installing
something in one does not give it to the others. sync fixes that with a union:
whatever any provider has, every selected provider gets.
It only ever adds and overwrites; nothing is deleted, and any file it replaces
is copied to <name>.archductor-backup first. Run sync-plan before sync —
the preview is the whole point of them being separate commands.
Known rough edges
- Terminal rendering handles common ANSI and control redraws but is not a full
terminal emulator. Programs that assume one may render wrong.
- Pull-request review-thread resolve and reopen are CLI-only
(
archductor pr resolve-thread, archductor pr reopen-thread).
- There is no product policy yet for Codex unsafe-approval or sandbox bypass.
Treat approval modes as something you set deliberately, per session.
