# auden

Local-first CLI for [Auden](https://app.auden.to) — a feedback layer for AI coding agents. Auden grades what your agents actually did against the guides you write (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, …) and shows you which instructions work.

The CLI is the on-device half of the product: it hooks into your agent's lifecycle, records what each tool call did, and syncs **only action metadata** to your dashboard, which grades the run against your guides. Raw hook data, file contents, and conversation transcripts never leave your machine.

## Install

```bash
npm install -g auden
```

A global install is required (not just `npx`). The hooks `auden init` registers run from your agent's session by name — `auden-hook` on every tool call, `auden sync` at the end of each turn and of the session — so both binaries must be on `PATH`. Node 20+ required.

## Staying up to date

```bash
auden update           # update to the latest release
auden update --check   # look, but don't install
```

`auden update` works out how you installed the CLI (npm, bun, pnpm, yarn) and runs the matching command, staying on whichever channel you're on — an `auden@alpha` install updates to the next alpha, not to stable. If it can't tell how you installed it, it prints the command instead of guessing.

**Auden never updates itself in the background.** New code is only ever installed when you ask for it. Bundled skills in your repo's `.claude/skills/` are never rewritten silently — you may have edited them, so `auden doctor` reports drift and leaves the fix to you:

```bash
auden init --skills-only   # rewrite just the bundled skills, nothing else
```

Use `--skills-only` rather than `--force` for this: `auden init --force` also resets `~/.auden/config.json` to defaults (discarding your stored API token) and replaces `AGENTS.md`.

The action logger is the `auden-hook` binary from this package — upgrading the CLI upgrades the logger.

Interactive commands check for a newer release at most once a day and print a one-line notice on stderr. The check is skipped entirely unless both stdout and stderr are terminals, so agent hooks, the MCP server, pipes, and CI never trigger it. To turn it off:

```bash
export AUDEN_NO_UPDATE_CHECK=1          # or NO_UPDATE_NOTIFIER=1
```

…or set `"updateCheck": false` in `~/.auden/config.json`. The check reads npm's public registry for the published version number only; it sends nothing about you or your machine.

## Quick start

```bash
cd your-project
auden init     # no token or account needed
auden doctor   # verify hooks + config
```

`auden init` detects Claude Code, registers a PostToolUse action-logging hook plus Stop and SessionEnd hooks that run `auden sync`, scaffolds `AGENTS.md` if missing, and installs a user-invocable Claude Code skill. Hooks, logging, and the local guide cache work without an account; grading needs one, because it runs on the dashboard.

The PostToolUse hook is written as the bare command `auden-hook`, a second binary this package installs alongside `auden`. It is a separate bin rather than an `auden hook` subcommand for two reasons: it runs once per tool call, where booting the full command tree would cost roughly 50ms every time; and a bare command resolved through `PATH` carries nothing machine-specific, so `.claude/settings.json` is identical on every machine and can be committed without churning.

To send your sessions to the dashboard, connect once with a CLI token (dashboard → Settings → Developer → CLI Token):

```bash
auden sync --token <token>   # remembered after the first successful sync
```

(`auden init --token <token>` also stores it, if you prefer one step.) Then just work normally — your dashboard feed fills in as your agent acts.

## Commands

| Command | What it does |
|---|---|
| `auden init` | Set up hooks, config (`~/.auden/`), and the Claude Code skill (`--skills-only` rewrites just the bundled skills) |
| `auden doctor` | Check your environment for common setup issues |
| `auden sync` | Upload logged actions + extracted feedback for grading, pull the guide bundle (run by the Stop and SessionEnd hooks) |
| `auden pull <bundle>` | Pull a context bundle's canonical items into a local directory as Markdown (default `.auden/context/<bundle>/`) |
| `auden mcp` | Run the Auden MCP server, exposing your context layer (bundles + inbox) to any agent |
| `auden import` | Adopt this repo's existing guide files (`AGENTS.md`, `.agents/`, `CLAUDE.md`, `.claude/rules/`, `.cursorrules`, `.cursor/rules/*.mdc`) into your dashboard — pick from a list, never type a path |
| `auden guides active` / `search` | List or search your synced guides |
| `auden suggest` | Review pending guide suggestions |
| `auden status` | Show pending actions + config status |
| `auden update` | Update the CLI to the latest release (`--check` to look without installing) |

### Bringing an existing repo's guides in

If the repo already has an `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, or skills, `auden init` finds them and offers to import them once a token is configured (`--import-guides` / `--no-import-guides` to answer without the prompt). To do it later, or after adding a new guide file:

```bash
auden import                     # pick from a list; Enter takes all of them
auden import --yes               # no prompt (required when stdin is not a TTY)
auden import --global            # also scan ~/.claude/CLAUDE.md
```

Files a context bundle already manages are **listed as managed** rather than hidden,
and cannot be selected — they are canonical in the dashboard, so edit them there or
on disk and run `auden sync`.

Re-run `auden import` after editing a guide file. There is no file watcher: a
watcher pushed one import per save, and because import has no update path, each save
filed a *new* guide row rather than updating the existing one. Continuous guide sync
returns via `auden sync` once guides have stable identity — see
[`guide-versioned-identity-plan.md`](../../docs/plans/guide-versioned-identity-plan.md).

It reads the dashboard URL from `~/.auden/config.json`, so a `--dashboard-url` passed to `auden init` (e.g. a staging dashboard) carries over; `--dashboard-url` overrides it for a single call. Auden's own bundled skills (`.claude/skills/auden/`, `.claude/skills/auden-context/`) are never imported.

## Privacy

- The CLI runs no LLM calls and holds no provider credentials. Grading happens on the dashboard, over the action metadata and guide text you synced — never file contents.
- Only action metadata and guide file content you explicitly import are synced. Shell command text is secret-redacted and length-capped before it is recorded at all.
- No telemetry.

## Links

- Dashboard: https://app.auden.to