local-agent — CLI cheatsheet¶

A local-first org-navigator. Everything stays on your machine.

Run as uv run local-agent <command> from the project dir, or pip install -e . for a bare local-agent. Suggested alias (clears a stale VIRTUAL_ENV after relocating the repo):

alias la='env -u VIRTUAL_ENV uv run local-agent'   # run from this directory
# or, from anywhere: alias la='/path/to/tool-chest/local-agent/la'

Store: a single SQLite file — --db PATH, else $LOCAL_AGENT_DB, else ~/.local/share/local-agent/store.db (auto-created). Back it up by copying it.

Capture¶

Command	Example	Does
`capture`	`la capture`	guided prompt — add a person + optional note + optional link interactively
`import FILE`	`la import meeting.json`	bulk import from JSON or CSV (see format below)
`person NAME [opts]`	`la person "Alice Chen" --team SPEAR --role "Staff Eng"`	add a person (terse, one-liner)
`person NAME --me`	`la person "Me" --me`	mark yourself — do this first (the anchor for reach queries)
`link A B [--kind K]`	`la link Me Alice`	connect two people (default `collaborates_with`)
`note TEXT [opts]`	`la note "Needs feature X" --for Alice --owe`	capture a note or commitment
`touch P [--when D]`	`la touch Alice`	record contact (sets `last_contact`; today by default)

person options: --team · --role · --org · --alias A (repeatable) · --tag T (repeatable) · --me link --kind: reports_to · collaborates_with · knows note options: --for P · --kind (requirement·followup·observation) · --status (open·done) · --due DATE · --owe (I owe them) · --owed (owed to me)

Import format (JSON)¶

Each record is an object in a top-level array. type defaults to "person".

[
  { "name": "Alice Chen", "team": "SPEAR", "role": "Staff Eng",
    "note": "Working on API redesign", "link_to": "Me" },

  { "type": "note", "text": "Send threat model", "for": "Alice", "owe": true, "due": "2026-06-19" },

  { "type": "touch", "person": "Alice", "when": "2026-06-12" }
]

CSV is also supported (column headers match the JSON keys). Good for pasting a list of meeting attendees.

Maintenance¶

Command	Example	Does
`person list [--team T]`	`la person list`	list people with ids (tabular)
`note list`	`la note list`	list notes with ids (tabular)
`link list`	`la link list`	list links with ids (tabular)
`delete person ID`	`la delete person 4`	remove a person (and their links/notes)
`delete note ID`	`la delete note 7`	remove a note
`delete link ID`	`la delete link 2`	remove a link between two people
`reset --yes`	`la reset --yes`	wipe the entire store (for experiment resets)

Use the list commands to find ids before deleting. --yes is required on reset to avoid accidents.

Query¶

Command	Example	Does
`who TEAM [--depth N]`	`la who SPEAR`	who I know on a team (1^st/2^nd degree), with the route
`intro P`	`la intro Carol`	shortest warm-intro route to someone
`brief P`	`la brief Alice`	dossier — relationships, notes, how I reach them
`owe`	`la owe`	open commitments I owe
`owed`	`la owed`	open commitments owed to me
`people [--team T]`	`la people --team SPEAR`	list people (alias for `person list`)

Referring to people¶

Anywhere a command takes a person, use a name (exact match first, then case-insensitive substring) or a numeric id. If a name is ambiguous, the tool lists the candidates with their ids — re-run with the id.

la brief bob        # → "bob is ambiguous: Bob Smith [id 4], Bob Jones [id 7]. Use the id."
la brief 4

The fast capture loop (the whole point)¶

Mid-conversation, one line — keep it cheap or you won't do it:

la note "raised flaky CI in standup" --for bob
la note "promised Dana the threat model by Fri" --for dana --owe --due 2026-06-19 --kind requirement

Then, when it matters:

la owe              # what am I behind on?
la who SPEAR        # who can I already reach on a team?
la intro "VP Eng"   # who's my warmest path to someone I don't know?
la brief bob        # before a 1:1

Chat capture (local model)¶

Talk instead of typing flags — a local model translates sentences into la commands. No data leaves the machine.

Command	Does
`./chat`	start local chat capture (Claude Code on a local Ollama model)
`LOCAL_AGENT_MODEL=<tag> ./chat`	one-off model override (must be local; `:cloud` is refused)
`make audit`	prove privacy: config attestation (no sudo)
`sudo -E make audit`	full proof: + deny-egress run + packet evidence

Model selection: edit [local_agent] model in ../tool-chest.toml — one place for the whole workspace.

See README → "Chat capture" for setup and the privacy contract.

Not yet (deferred, seams in place)¶

Cadence/staleness ("who should I reconnect with") via last_contact, semantic "who knows about X" via the vector seam, and the local-model/cloud layers — all wait on real use pulling them in. If a query you keep reaching for is missing, that's the signal to build it.