ljos

# ljos

Tell your coding agent a rule once. It comes back on every prompt it bears
on, and the hook refuses the command that breaks it.

Coding agents forget what they learned when the session ends, and they run
whatever shell command they pick. ljos fixes both on your own machine. It
keeps what you tell the agent in a local store and hands the matching notes
back before the model reads each prompt. It checks each shell command against
your rules and a built-in list of destructive commands before the command
runs. It plugs into the agent through the agent's own hook and MCP settings.
Nothing leaves the machine unless you turn on a remote judge.

It works with Claude Code, Codex, Cursor, GitHub Copilot CLI, Gemini CLI,
Windsurf, Factory's Droid, Kiro, Cline, Qwen Code, Crush, Auggie, Amp, goose,
OpenHands, Continue, Roo Code, Kilo Code, Grok Build, opencode, omp, hermes
and Antigravity's `agy`.

## Five minutes

```
curl -fsSLO https://github.com/leidarljos/ljos/releases/latest/download/install.sh && sh install.sh
ljos prefer "Tag a release with git push origin TAG; --follow-tags leaves v-tags behind."
ljos rule 'terraform destroy*' --verdict deny --why "Destroy only from the release runbook."
```

The installer downloads each program from its GitHub release, checks it
against the published SHA-256 sum, and builds from source with `cargo` where a
platform has no release. It then runs `ljos onboard` for every coding agent it
finds and shows the guard refusing a force push. Its programs are ljos,
packset (memory), vissue (the tracker), deedar (records of work), claimdag
(who works on what), ljos-policyd (the command check) and ljos-consensus
(voting), plus `packset-embed`, the encoder for meaning-based search.
`--no-embed` leaves the encoder out; search then matches words only and misses
a paraphrase that shares no word with the memory. Where a platform has no
encoder build, the installer warns and goes on without it. `--with-embed` is
still accepted and changes nothing. `ljos doctor` names any part that is missing.
`--version 0.29.0` installs that ljos release instead of the latest, and `--pin packset=0.14.0` holds another repository at a version; a pinned version with no release for the platform builds that version's crate, never a newer one.
With the `gh` CLI signed in, the installer also checks each tarball's GitHub build attestation and prints whether it verified; `--attest` stops the install when one does not.
`ljos-hud`, the desktop pane, is optional, and the doctor lists it as `info`.
An `ljos-policyd` built without phronesis checks commands with its table alone, and the doctor marks its policy row `warn`.
Building from source (`cargo install`, or binstall on a platform with no release tarball) needs Rust 1.89 or newer; `rustc --version` says which you have, and `rustup update stable` gets a current one.
An older Rust fails on several crates and can leave an `ljos-policyd` older than 0.3.0 installed without a word, so the doctor marks that row `no` and names the fix.

Each ljos release from 0.29.0 on attaches the script as `install.sh`.
Read the script before you run it; it is
`scripts/install.sh` in this repository. To install by hand:

```
cargo binstall --locked ljos packset vissue-cli vissue-mcp deedar-cli claimdag-cli ljos-policyd ljos-consensus   # or: cargo install --locked, same list
ljos onboard                                # every coding tool found on this machine: MCP server, hooks and skill
ljos prefer "Tag a release with git push origin TAG; --follow-tags leaves v-tags behind."
ljos rule 'terraform destroy*' --verdict deny --why "Infra teardown is mine to run."
```

`--harness` takes `claude`, `codex`, `grok`, `cursor`, `antigravity`,
`opencode`, `omp`, `hermes`, `windsurf`, `zed`, `vscode`, `claude-desktop`,
`gemini`, `amazonq`, `kiro`, `copilot`, `factory`, `qwen`, `crush`, `cline`,
`auggie`, `amp`, `goose`, `openhands`, `continue`, `roo` or `kilo`.
Cursor's IDE and its `agent` CLI share `~/.cursor/mcp.json`.

Start a new session and ask for something the preference bears on, such as
tagging a release. Before the model reads the prompt, the hook adds:

```
What this seat already knows that bears on this (from the pack, each with its age, lessons oldest first; `ljos search` for more):
- [preference, today] Tag a release with git push origin TAG; --follow-tags leaves v-tags behind.
```

When the agent then reaches for `git push --force origin main`, the runner
asks before it runs. `ljos-policyd` answers first, with the rules it ships,
and lets `--force-with-lease` through:

```
{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"git-force-push: a force push rewrites history that others may already have pulled. Push without --force, use --force-with-lease to overwrite only your own last push, or ask the person to run it (seat rule `git-force-push`)"}}
```

`sh -c "cd repo && git push -f origin main"` gets the same answer. A command
only your own rule covers, such as `terraform destroy -auto-approve`, meets
that rule:

```
{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Infra teardown is mine to run. (seat rule `terraform destroy*`)"}}
```

The hook shows what you write from the moment it is written: a preference
(`ljos prefer`), a rule (`ljos rule`), and a lesson you type with
`ljos remember`. A lesson the agent proposes at `ljos finish` stays out until
you run `ljos accept ID` in your own terminal; then it shows at once too. An
`ljos remember` that an agent runs from inside its runner is an episode: the
hook shows it when a prompt bears on it, and `ljos due` lists it until a
review promotes it to standing.

The hooks also keep the work on the tracker once a conversation sits on an
issue: after forty tool calls without a word to the seat, they remind it to
record the work. With `LJOS_TRACK_WORK=on` in the environment or in
`~/.config/ljos/env`, a conversation with no issue is told on the first tool
result to open one with `vissue q` and sit, and `Stop` blocks that turn once
if it used tools and never touched the seat. Without it, a conversation that
never sits hears nothing about the tracker. Of the shapes ljos carries, `grok` and
`antigravity` register `Stop`. For `claude` or `codex`, add `Stop` to that
runner's `hook_events` in `~/.config/ljos/harnesses.toml`.

## What you get

- Memory per prompt: one claim per memory, searched with the prompt. A claim
  reaches the agent only when it shares the prompt's words or a judge is sure
  it bears on the prompt. Lessons come back on a review clock, and a newer
  claim supersedes a wrong one instead of editing it.
- A tracker, [vissue](https://github.com/leidarljos/vissue): plain org files
  in a git repository. `ljos sitting ISSUE` opens the work and claims it;
  `ljos finish ISSUE --lesson "..."` closes the loop and files what it
  taught. `ljos accept ID` writes that lesson and records the acceptance.
- A check on shell commands: ljos-policyd's built-in refusals (force push,
  `rm -rf` outside temp, `git reset --hard` and the like, read through `env`,
  `timeout`, `xargs` and other wrappers) and your rules in the pack
  (`ljos rule`), tried on each command a line runs, plus a guard that keeps agents from rewriting the
  checker's own binaries and hook files. An ordinary `git push` of a branch
  is allowed, whichever remote it names and whether or not that remote's
  owner can be read. Force (`--force`, `-f`, `--force-with-lease`, a
  `+refspec`), deleting a remote branch, and pushing tags ask by default,
  with or without a seat rule.
  A pattern as wide as `git push*` is refused when a rule is written.
- Decisions with more than one defensible answer go to personas, voters with
  a view of their own. They settle by trust-weighted
  [consensus](https://github.com/leidarljos/consensus) that learns from the
  outcome. A persona can reason in a runner session it keeps.
- Deeds ([deedar](https://github.com/leidarljos/deedar)): content-addressed
  records of what a piece of work produced, cited on the ticket.

## Words

| word | meaning |
|---|---|
| seat | one agent runner on one machine, with its memory and claims |
| pack | the memory store ([packset](https://github.com/leidarljos/packset)), one claim per atom |
| sitting | one piece of work on one ticket, opened by `ljos sitting` and closed by `ljos finish` |
| island | the memories a title activates, and the links between them |
| deed | a signed record of what a piece of work produced |
| card | a file the person froze; agents read it and never write it |
| persona | a voter with a view, an anchor and the domains it speaks to |

## The loop, in two verbs

`ljos sitting ISSUE [--playbook NAME]` opens a sitting. It runs the steps in
the protocol's order and stops at the first store that does not answer:
doctor, cards, the review clock, the island the issue's title activates, the
playbook, the working set, the timeline, and the claim. The playbook gets
copied before recall. Without `--playbook`, the sitting takes a name already
bound, then a closed-set token in the title, then `sit`. The playbook name
lives as a tracker note until finish or release, and `ljos panel` refuses to
run until one is bound.
The sitting prints a short report: whether ljos is ready, what needs action, what the seat remembers for the task, and the claim.
`--verbose` prints every section in full.

`ljos finish ISSUE --lesson "..." [--outcome OPTION]` closes it. The lesson
goes in as a proposal with origin `agent-derived`. `ljos accept` writes it as a
standing lesson and records that the person accepted it. Under an agent runner
it accepts only a proposal another conversation filed, such as a worker's, so
an agent can't accept its own proposal. A lesson you type at `ljos finish` in a
terminal of your own, with no agent runner above it, is written at once as
yours. `ljos accept`, `ljos forget` and `ljos graded`