# Install and start — OneCue

> OneCue is the decision layer for coding agents. It surfaces the recorded decisions that bear on the task — what was chosen, why, and what each rules out — right before your agent changes the code. Usually one, a few when the task spans several, each with its source, or silence. Local-first: OneCue’s store never leaves your machine, though your coding agent’s own model provider still sees your code.

Three commands in. Decisions on every prompt. The skill teaches Claude Code to
capture decisions; the CLI makes recall automatic.

## 1. Run the installer inside your repository

```sh
curl -fsSL https://onecue.sh/install.sh | sh
```

Inside a git repo it installs the `onecue` CLI 0.4.0 and runs
`onecue install`, which writes the skill, the recall hooks, and the local
store for each agent it detects.

- Decisions: `.onecue/decisions/` (git-visible Markdown)
- Logs: `~/.onecue/projects/<project-fingerprint>/`
- Hooks: `.claude/settings.local.json` + `.devin/config.local.json`
- Skill: `.claude/skills/onecue` + `.devin/skills/onecue`

Prefer npm? `npm i -g onecue-cli`, then `onecue install`. Skill only, no
hooks? `npx skills add onecueai/onecue-skill`.

Devin also reads `.claude/` hooks by default — set
`read_config_from.claude: false` in `~/.config/devin/config.json` for a
single source.

## 2. Save something worth keeping

```sh
onecue remember "Keep the job queue in Postgres — order and job commit atomically." --kind decision
```

Or tell Claude Code "remember that we chose Postgres for the job queue" and the
skill captures it.

Decision kinds:

- `decision` — a choice with the reason it was made, and what it rules out
- `insight` — a non-obvious lesson or root cause
- `open_loop` — unfinished work or a pending constraint
- `discovery` — an undocumented fact about the repo or system
- `reference` — an external pointer with a known future use

## 3. Let recall happen

With hooks installed, each new prompt gets the relevant decisions (usually one)
— silence when nothing applies.

```sh
onecue recall "add retries for failed jobs"
```

Browse the store any time: `onecue list`, `onecue show <id>`,
`onecue forget <id>`.

## 4. Verify the setup

```sh
onecue doctor
```

Runtime, store, per-agent hooks and skill, and decision-file integrity. Exits
non-zero on warnings, so it fits CI. No CLI? The companion skill ships the same
checks: `npx skills add onecueai/onecue-doctor`.

## Command reference

- `onecue init` — Create the git-visible .onecue/decisions/ store
- `onecue install` — Install skill + hooks for detected agents [--harness claude,devin,cursor,codex]
- `onecue uninstall` — Remove only OneCue's hooks (decisions are kept)
- `onecue status` — Initialization, hooks, and decision counts
- `onecue statusline` — One-line status for the agent status bar (decisions, cues this session, local)
- `onecue doctor` — Diagnose the setup, decision graph, and spend report [--json]
- `onecue bench` — Run the decision-selection benchmark [--json]
- `onecue remember <text>` — Record a decision [--kind …] [--reason …] [--files a,b] [--rejected] [--rules-out a,b] [--supersedes <id>] [--conflicts-with <id>]
- `onecue recall <context>` — Print the cue this context would surface [--json]
- `onecue list` — List decisions [--kind <k>] [--json]
- `onecue show <id>` — Show one decision (id or prefix)
- `onecue forget <id>` — Tombstone one decision (file kept, excluded from recall)
- `onecue hook <event>` — Invoked by the agent harness, not by hand

## Decision relationships

Decisions can point at each other, and recall reads the links:

- `--supersedes <id>` — a newer decision replaces an older one. Recall surfaces
  only the current head of the chain and never the retired ancestor; `list`
  marks the old one `(superseded)`.
- `--conflicts-with <id>` — two active decisions disagree. Recall surfaces the
  match **and** warns that it conflicts, so the agent resolves it instead of
  silently picking a side.

`onecue doctor` summarizes the graph: how many conflicts, cycles, and decisions
retired by a supersede.

One canonical store: with the CLI installed, decisions live as Markdown in
`.onecue/decisions/` (committed with your repo). Without the CLI, the skill
falls back to `.onecue/memories/`, and `onecue doctor` flags any that still
need importing.

Next: [Docs](https://onecue.sh/docs) · [Session examples](https://onecue.sh/examples)