> ## Documentation Index
> Fetch the complete documentation index at: https://docs.driftless.icu/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI: Agents and hooks

> Configure and inspect the server-side agents (BYOM), and manage the local auto-pull hook.

Two things live here: the `agent` family configures and inspects the server-side agents ([Auditor, Architect, Librarian](/agents/agentic-layer)), and the `hook` / `hooks` commands manage the local [auto-pull](/concepts/automations) hook. They are unrelated: `agent` talks to the server, `hooks` edits a local file. Add `--json` to any `agent` command for machine output.

## Agent runs and config

The agents run automatically server-side; the CLI inspects and configures them. There is no manual run-trigger command (it was retired).

| Command                            | Description                                             |
| ---------------------------------- | ------------------------------------------------------- |
| `agent runs [--limit <n>]`         | Recent runs (id, agent, status, time).                  |
| `agent run <id>`                   | One run with its full trace.                            |
| `agent config [--show]`            | Print the current config. Secret keys are never echoed. |
| `agent config --set <key>=<value>` | Set a config key (repeatable).                          |
| `agent usage [--days <n>]`         | Token and cost rollup.                                  |
| `agent stats`                      | Proposal acceptance stats.                              |
| `agent models`                     | The BYOM model catalog.                                 |

## BYOM configuration

Settable keys on `agent config --set`: `opencode_key` (the bring-your-own-model key, write-only), `model` (a comma-separated priority list of `provider/model`; the runner rotates on a rate-limit or credit error), and the toggles `auditor`, `architect`, `librarian`, and `librarian_autovouch`.

```bash theme={"theme":"github-light"}
driftless agent config --set opencode_key=oc_xxx --set model="opencode/claude-sonnet-4-6"
driftless agent config --set auditor=true --set architect=true
driftless agent config --show    # key is redacted
```

Each agent is off until its toggle is on and a model key is configured; otherwise a run records a `no_op`.

## Hooks (auto-pull)

The auto-pull hook is a local Claude Code feature, off by default. Two commands manage it, and they are different:

| Command                                  | Description                                                                            |
| ---------------------------------------- | -------------------------------------------------------------------------------------- |
| `hook <pre-edit\|post-edit\|stop\|sync>` | The runtime glue Claude Code invokes. You never run it by hand.                        |
| `hooks enable`                           | Install the hook entries into `.claude/settings.json` (PreToolUse, PostToolUse, Stop). |
| `hooks disable`                          | Remove those entries from this machine.                                                |

Installing the hook is inert until a workspace admin turns on the `auto_pull_context` toggle in the dashboard. Only Knowledge (`reviewed`) topics ever inject.

```bash theme={"theme":"github-light"}
driftless install-skill    # installs the hook, inert
driftless hooks disable    # remove it from this machine
```

## Permissions

Reading agent runs and setting BYOM config are workspace-member actions from the CLI. The agent-runs surface is not reachable over OAuth/MCP (agent runs spend model inference); the MCP surface exposes only `driftless_agent_stats`.

## Related

* [Audit, Architect, and Librarian agents](/agents/agentic-layer) - what the agents do.
* [Auto-pull](/concepts/automations) - the local hook, in depth.