Connect and review

Connect the agent for your user account:

writ connect <agent>

Use claude, codex, cursor, or opencode as the agent. The command does not change the agent’s MCP configuration. It does not need an MCP server, writ file, or model key.

Connect the agent

This example uses Codex:

writ connect codex

The command reports the scope, coverage, and next step:

Connected Codex to Writ.
  Built-in tools: limited
  MCP tools: watching
  Remote MCP tools: watching
  Hosted tools: not visible
Scope: global.
Writ now records visible tool calls.
Nothing is blocked.
Start or restart Codex. Use it as usual.
After a tool call, review what happened:
  writ review

Start or restart the agent. Use it as usual. Writ creates a project record when the agent sends the first tool event.

Review what happened

Run this command from the project:

writ review

Use writ review codex when the project has runs from more than one agent. The review includes the reported tool name, visible arguments, decision, reported result, and coverage metadata. Writ redacts built-in secret patterns before it stores an entry.

Writ stores the record under ~/.writ/projects/<project-id>/record.db. It does not create a project .writ directory.

Limit the connection to one project

Use --project when the agent should connect only in the current project:

writ connect codex --project

The default user connection and a project connection can exist together. Writ applies both tool limits. The project connection can narrow the user limit. It cannot widen it.

Writ writes user hooks to these locations:

Agent	User hook
Claude	$CLAUDE_CONFIG_DIR/settings.json or ~/.claude/settings.json
Codex	$CODEX_HOME/hooks.json or ~/.codex/hooks.json
Cursor	~/.cursor/hooks.json
OpenCode	$XDG_CONFIG_HOME/opencode/plugins/writ.ts or ~/.config/opencode/plugins/writ.ts

With --project, Writ uses the matching agent hook path inside the project.

Check or remove a connection

Check the user connection:

writ connect status codex

Check the project connection:

writ connect status codex --project

The status has four coverage rows: built-in tools, local MCP tools, remote MCP tools, and hosted tools. watching means Writ records the boundary. enforcing means Writ can stop a reported pre-tool event. limited and not visible state gaps in the agent hook.

Remove the selected connection:

writ disconnect codex
writ disconnect codex --project

Writ removes only the hook entries that it installed. It preserves other hooks and existing records. It refuses to overwrite a Writ-owned hook that changed after connection.

When you connect from a Git worktree, Writ adds /.writ/ to the local .git/info/exclude. It does not change the shared .gitignore. This keeps a local .writ directory out of Git.

Flags

Flag	Result
--read-only	Allow normalized read and search tools. Stop other calls.
--allow <name>	Allow one exact agent or normalized tool name. Repeat for more names.
--project	Install or select the current project’s connection.

Use only one limit form. Pattern syntax is not accepted by --allow.

Continue with Add a tool limit.