Skip to content
Back to search

alnair

SkillWorks with CodexGitHub

Claude Code and Codex with a model router, memory that survives compaction, and answers checked against their sources.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mahimn01--alnair/badge.svg)](/listings/mahimn01--alnair)

HTML

<a href="/listings/mahimn01--alnair"><img src="/api/listings/mahimn01--alnair/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

You need Python 3.10+, Node 20+, git, and [Claude Code](https://code.claude.com/docs/en/setup) installed with Anthropic's native installer and signed in once. On Debian and Ubuntu, Python's venv module is a separate package, so run `sudo apt install python3-venv` first.

macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/mahimn01/alnair/main/get.sh | bash
alnair doctor     # checks the install offline, with no model call
alnair            # start a session in the current folder

Windows 10 and 11, in PowerShell, with no WSL (Git for Windows must be installed):

irm https://raw.githubusercontent.com/mahimn01/alnair/main/get.ps1 | iex
alnair doctor

Everything the installer does:

- clones this repository into `~/alnair`, makes a Python venv inside it, and installs the optional page-extraction package into that venv - links `alnair` (and its old name, `claude-lab-clp`) into `~/.local/bin` - creates `~/.clp` for memory and saved research, run folders under `~/.local/state`, and `~/.config/alnair/config.env` for settings - if the Codex CLI is installed, adds two MCP servers to `~/.codex/config.toml` between marker comments, after saving a backup

It never writes `~/.claude/settings.json`, `~/.claude.json` or anything else under `~/.claude`. If you would rather read before you run, [get.sh](get.sh) and [install.sh](install.sh) are short, or clone the repository and run `./install.sh` yourself. [docs/install.md](docs/install.md) covers the options, updating and [removing it](docs/install.md#removing-it).

For GPT models, install the Codex CLI, run `codex login`, and start `alnair --model gpt`. Details are in [docs/codex.md](docs/codex.md).

Where session notes go

When a session ends, Alnair writes one Markdown note about it into a `Claude Sessions` folder inside your notes folder. The setting `ALNAIR_VAULT` names the notes folder. If you don't set it, the notes folder is `~/Documents/Obsidian Vault`, and it is created if it isn't there. You don't need Obsidian for this; the notes are plain Markdown files.

To use a folder of your own:

- when you install: `curl -fsSL https://raw.githubusercontent.com/mahimn01/alnair/main/get.sh | ALNAIR_VAULT=~/Notes bash` (in PowerShell, run `$env:ALNAIR_VAULT = 'D:\Notes'` before the `irm` line) - later: add the line `ALNAIR_VAULT=~/Notes` to `~/.config/alnair/config.env`

Changing it later doesn't move notes that are already written. [docs/install.md](docs/install.md#your-notes-folder) has the details.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 237 lines · 2 findings marked
  1. # Alnair
  2. [![CI](https://github.com/mahimn01/alnair/actions/workflows/ci.yml/badge.svg)](https://github.com/mahimn01/alnair/actions/workflows/ci.yml)
  3. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  4. **Claude Code and Codex with a model router, memory that survives compaction, and answers checked against their sources.**
  5. Alnair is a launcher for the Claude Code and Codex command-line tools. It starts their normal interactive session on your own subscription and adds three things. It picks the Claude model for each task. It keeps what a long session settled in a ledger the model can read back. And it refuses an answer whose quote is not in the file or page it cites. It never edits `~/.claude`.
  6. ![Terminal recording: the verify gate indexes two sample notes, passes an answer that quotes them word for word, and refuses one where 25% became 20%](docs/demo/verify-gate.gif)
  7. *A recording of [examples/verify-gate.sh](examples/verify-gate.sh), which makes no model call. The gate passes an answer that quotes the note word for word and refuses one where 25% became 20%. The recording waits before each step so you can read it; the script itself takes about a second. You can [run it yourself](#try-the-verify-gate-without-a-session).*
  8. ## Why I built it
  9. My long sessions kept hitting the same three problems.
  10. - **Opus got spent on renaming variables.** A session runs every task on the model it started with unless you switch by hand.
  11. - **Important facts vanished at compaction.** Once the context was summarised, a decision from an hour earlier could be gone.
  12. - **Research answers cited pages that didn't say what the answer claimed.**
  13. Alnair is the harness I use every day to deal with those three. It is still Claude Code or Codex underneath, so what you already know about them carries over.
  14. ## What you get
  15. - **Model routing for Claude.** Each task goes to Sonnet, Opus or Fable based on what you asked. You can override it per launch (`--model opus`) or per task (`/lab-model`).
  16. - **Session memory that survives compaction.** Durable facts go into a ledger under `~/.clp/sessions/<id>/`, each with a file address and a SHA-256. A read whose hash no longer matches is refused, so stale memory can't come back as fact.
  17. - **A verify gate for your notes.** CLP (Context Ledger Protocol) indexes a copy of your notes folder. The model looks things up, reads the exact lines, and runs `verify` before presenting a claim. A claim whose quote isn't in the cited lines is refused. You can [try the gate yourself](#try-the-verify-gate-without-a-session) in half a minute.
  18. - **Research tools that need no API keys.** Papers (arXiv, OpenAlex, Crossref, Semantic Scholar), SEC filings, patents, court records, Wayback snapshots and market data. A research report only passes when every quote matches the saved source word for word.
  19. - **Claude and GPT in one harness.** `alnair --model gpt` runs the Codex CLI on your ChatGPT login with the same memory and research tools, and both write to the same session ledger.
  20. - **Session notes.** When a session stops, ends or compacts, a hook writes one Markdown note for it into your notes folder (Obsidian works). It only ever edits the notes it created.
  21. - **Interactive only, on your subscription.** `-p`/`--print`, `codex exec` and the other headless modes are refused, and there's no API-key fallback, so a session can't quietly start billing an API account.
  22. The memory layer comes from my research on CLP. The protocol, its paper experiments and the measured results are in [mahimn01/context-ledger](https://github.com/mahimn01/context-ledger). This repo is the day-to-day harness built on it.
  23. ## Quickstart
  24. You need Python 3.10+, Node 20+, git, and [Claude Code](https://code.claude.com/docs/en/setup) installed with Anthropic's native installer and signed in once. On Debian and Ubuntu, Python's venv module is a separate package, so run `sudo apt install python3-venv` first.
  25. macOS and Linux:
  26. ```sh
  27. curl -fsSL https://raw.githubusercontent.com/mahimn01/alnair/main/get.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 43 on GitHub
  28. alnair doctor # checks the install offline, with no model call
  29. alnair # start a session in the current folder
  30. ```
  31. Windows 10 and 11, in PowerShell, with no WSL (Git for Windows must be installed):
  32. ```powershell
  33. irm https://raw.githubusercontent.com/mahimn01/alnair/main/get.ps1 | iex
  34. alnair doctor
  35. ```
  36. Everything the installer does:
  37. - clones this repository into `~/alnair`, makes a Python venv inside it, and installs the optional page-extraction package into that venv
  38. - links `alnair` (and its old name, `claude-lab-clp`) into `~/.local/bin`
  39. - creates `~/.clp` for memory and saved research, run folders under `~/.local/state`, and `~/.config/alnair/config.env` for settings
  40. - if the Codex CLI is installed, adds two MCP servers to `~/.codex/config.toml` between marker comments, after saving a backup
  41. It never writes `~/.claude/settings.json`, `~/.claude.json` or anything else under `~/.claude`. If you would rather read before you run, [get.sh](get.sh) and [install.sh](install.sh) are short, or clone the repository and run `./install.sh` yourself. [docs/install.md](docs/install.md) covers the options, updating and [removing it](docs/install.md#removing-it).
  42. For GPT models, install the Codex CLI, run `codex login`, and start `alnair --model gpt`. Details are in [docs/codex.md](docs/codex.md).
  43. ### Where session notes go
  44. When a session ends, Alnair writes one Markdown note about it into a `Claude Sessions` folder inside your notes folder. The setting `ALNAIR_VAULT` names the notes folder. If you don't set it, the notes folder is `~/Documents/Obsidian Vault`, and it is created if it isn't there. You don't need Obsidian for this; the notes are plain Markdown files.
  45. To use a folder of your own:
  46. - when you install: `curl -fsSL https://raw.githubusercontent.com/mahimn01/alnair/main/get.sh | ALNAIR_VAULT=~/Notes bash` (in PowerShell, run `$env:ALNAIR_VAULT = 'D:\Notes'` before the `irm` line)
  47. - later: add the line `ALNAIR_VAULT=~/Notes` to `~/.config/alnair/config.env`
  48. Changing it later doesn't move notes that are already written. [docs/install.md](docs/install.md#your-notes-folder) has the details.
  49. ## Try the verify gate without a session
  50. This runs the gate on a two-note sample. It makes no model call, uses no network, and writes only to a temporary folder that it deletes.
  51. ```sh
  52. ~/alnair/examples/verify-gate.sh
  53. ```
  54. The last three of its five steps print this. It is real output, copied from a run:
  55. ```text
  56. == 3. Read the exact lines at AMZN.md:1-4#a07561d9
  57. [AMZN.md:1-4#a07561d9] lines 1-4 of 5
  58. # AMZN
  59. Exit plan: sell if a daily close is 25% below the highest close since the first buy.
  60. Working order: BUY 22 @ $223 GTC.
  61. == 4. Verify an answer that quotes the note word for word
  62. PASS: verified against your files.
  63. Answer: The exit plan is to sell if a daily close is 25% below the highest close since the first buy.
  64. Why: every claim quotes your files word for word, and every number or name in the answer is in those quotes.
  65. Sources:
  66. [1] AMZN.md lines 1-4: "sell if a daily close is 25% below the highest close since the first buy"
  67. Present the ANSWER and these claims as the verified part; label anything else you add as not verified.
  68. == 5. Verify an answer that gets the number wrong (25% became 20%)
  69. REFUSED: not verified (2 problems). Do not present this answer as fact.
  70. - claim 1, citation 1: the quote is not in AMZN.md:1-4 word for word. Read those lines again and copy the quote exactly, or cite the lines that hold it.
  71. - answer: `20` in the ANSWER line is not in any verbatim quote you cite. Quote the line that gives it, or leave it out.
  72. Repair: read the lines that hold each value, copy quotes exactly, and verify again; or answer UNANSWERABLE.
  73. ```
  74. Inside a session the model runs these same steps before it tells you what your notes say. `alnair demo` starts a session on a small demo project with this sample corpus.
  75. ## Everyday commands
  76. ```sh
  77. alnair # Claude session in the current folder
  78. alnair "fix the flaky test" # start with a prompt
  79. alnair --model opus "..." # pick the model yourself: auto (default), sonnet, opus, fable or gpt
  80. alnair --resume latest # pick up the last run with the same memory tools
  81. alnair --dry-run "..." # print the exact command and settings, start nothing
  82. alnair doctor # offline readiness report for Claude and Codex
  83. alnair --version
  84. ```
  85. ![alnair --help and a GPT dry run in a terminal](docs/terminal.png)
  86. *Real output of `alnair --help` and `alnair --model gpt --dry-run`, captured from a fresh clone in a scratch home folder and rendered as an image. A dry run starts no session.*
  87. Index your notes once so lookups have something to search. This copies the folder into `~/.clp` and never writes to the original:
  88. ```sh
  89. ~/alnair/.venv/bin/python ~/alnair/claude-clp/bin/clp_tool.py init ~/Notes
  90. ```
  91. The rest, including Remote Control and the Codex setup commands, is in [docs/usage.md](docs/usage.md).
  92. ## How it works
  93. ```mermaid
  94. flowchart LR
  95. you(["You"]) --> launcher["alnair launcher"]
  96. launcher -->|default| claude["Claude Code<br/>interactive session"]
  97. launcher -->|"--model gpt"| codex["Codex CLI<br/>interactive session"]
  98. claude --- lab["Lab plugin<br/>model router, guards, status line"]
  99. claude --- tools
  100. codex --- tools
  101. subgraph tools["Added to both"]
  102. clp["Memory tools<br/>lookup, read, verify, session ledger"]
  103. research["Research tools<br/>fetch, claim, report gate"]
  104. notes["Session-note hook"]
  105. end
  106. clp --> store[("~/.clp<br/>notes index and session ledgers")]
  107. research --> rstore[("~/.clp/research<br/>saved sources and claims")]
  108. notes --> vault[("Your notes folder")]
  109. ```
  110. `alnair` is a Python launcher. For a Claude session it builds a settings layer for that one run, loads its plugins with `--plugin-dir`, and starts `claude`. Nothing is installed into Claude Code itself, which is why your plain `claude` command behaves as before. For a GPT session it starts `codex` with the same memory and research tools attached as MCP servers.
  111. - **Lab plugin** (Claude only). Reads each prompt and picks the model, shows a status line, and guards the session: no nested or headless sessions, and no writes to your Claude settings files.
  112. - **Memory tools.** `lookup`, `read` and `verify` over an indexed copy of your notes, plus a ledger for each session. Every address carries a hash of the lines it points at.
  113. - **Research tools.** Fetch a source, save its exact text, record claims that quote it, and gate the final report against those claims.
  114. - **Session-note hook.** Writes one Markdown note per session into your notes folder.
  115. ## Model routing
  116. With `--model auto`, the default, the router reads your prompt:
  117. | Prompt looks like | Model | Effort |
  118. |---|---|---|
  119. | long-horizon or extremely hard work: open research problems, formal verification, many repositories | Fable if available, otherwise Opus | xhigh |
  120. | architecture, security, proofs, root causes, race conditions, anything ambiguous | Opus | xhigh |
  121. | brokerage or options-trading work | Sonnet, plus a required Opus review | high |
  122. | everything else | Sonnet | medium |
  123. Auto never picks GPT. Inside a session, `/lab-model auto|sonnet|opus|fable` sets the model for the next task. [docs/models.md](docs/models.md) has the rest: the Fable check, how new model aliases are picked up, and what subagents get.
  124. ## Compared with plain Claude Code
  125. | | Plain Claude Code | With Alnair |
  126. |---|---|---|
  127. | Model for each task | The one the session started with, until you switch with `/model` | Sonnet, Opus or Fable, picked from the prompt. You can override it |
  128. | After compaction | The session continues from a summary | The summary, plus a ledger of saved facts the model can look up, each checked by hash |
  129. | Answers about your notes | Not checked | `verify` refuses a claim whose quote isn't in the cited lines |
  130. | Research | Web search and page fetches | Keyless source tools that save what they fetch, and a report gate that checks every quote |
  131. | GPT models | No | `alnair --model gpt` runs Codex with the same memory |
  132. | Record of a session | Transcript files | One Markdown note per session in your notes folder |
  133. | Headless runs (`-p`) | Yes | Refused |
  134. | Billing | Subscription or API key | Subscription logins only |
  135. | Your Claude settings | Yours | Unchanged. Alnair passes its own layer for each run |
  136. What you give up: headless mode, API-key use, and some simplicity. Alnair needs Python and Node, adds hooks and tools to every session, and turns on Claude Code's experimental Code Mode by default (`--no-code-mode` turns it off, and [docs/code-mode.md](docs/code-mode.md) explains it).
  137. Your plain `claude` and `codex` commands behave as before. The only lasting change outside Alnair's own folders is the two MCP servers in `~/.codex/config.toml`, which plain `codex` sessions can use too.
  138. **Memory plugins that summarise past sessions** inject recalled text that the model can't check. Alnair's memory is addressed: every fact points at a file, a line range and a hash, and the verify gate refuses a quote that isn't there. Recall is weaker in exchange, because nothing gets remembered that wasn't written down.
  139. ## FAQ
  140. **Does it use my API key?** No. Claude sessions run on your Claude Code login and Codex sessions on your ChatGPT login. Alnair strips `OPENAI_API_KEY` and `CODEX_API_KEY` from Codex sessions. The only paid path is the optional `clp ask` command, which reads `CONTEXT_LEDGER_RESEARCH_API_KEY`, stops at a $5 daily cap, and isn't offered to Codex at all.
  141. **Will it change my settings?** It never writes Claude Code's settings. It reads `~/.claude/settings.json` to build the run's layer and passes that layer with `--settings`, and the test suite checks that a launch leaves those files byte-identical. On the Codex side, the installer adds one marked block to `~/.codex/config.toml` after a backup, and `alnair codex-setup --remove` takes it out again.
  142. **How do I remove it?** Run `alnair codex-setup --remove`, delete the two links in `~/.local/bin`, and delete `~/alnair`. [docs/install.md](docs/install.md#removing-it) lists the data folders that are left for you to keep or delete.
  143. **Why no headless mode?** The subscription I built it on refuses headless calls with a 403, and silently falling back to an API key is how surprise bills happen. The same rule covers `codex exec`.
  144. **Does it need Obsidian?** No. Any folder of Markdown, text or Python files works as the notes corpus, and session notes are plain Markdown.
  145. **Does it work on Linux and Windows?** The test suites run on macOS, Ubuntu and Windows in CI. I use macOS every day, so that is where it has had the most real use. On Linux the optional account switcher is missing because it needs the macOS Keychain. [docs/windows.md](docs/windows.md) covers Windows.
  146. ## Status
  147. Alnair is young. The first release was on 2026-11-17, and [CHANGELOG.md](CHANGELOG.md) lists what has changed since. I use it every day on macOS. The test suites hold more than 1,000 tests. They run against local stand-ins for the network and for the `claude` and `codex` programs, so they never start a model session or make a paid call. Code Mode support is experimental because the Claude Code feature is.
  148. ## Documentation
  149. [docs/](docs/README.md) has the full pages: [install](docs/install.md), [everyday use](docs/usage.md), [model routing](docs/models.md), [Codex and GPT](docs/codex.md), [Code Mode](docs/code-mode.md), [settings](docs/settings.md) and [Windows](docs/windows.md).
  150. The code is in five folders:
  151. - `claude-mem/` holds the `alnair` launcher (`bin/claude-lab-clp`), the Codex backend, the routing benchmark and an optional Rune terminal layout
  152. - `lab/` is the Claude session layer: model router, guards, status line and the optional account switcher ([lab/README.md](lab/README.md))
  153. - `claude-clp/` is the memory plugin, its MCP server for Codex, the session ledger and the session-note hook
  154. - `claude-research/` is the research plugin and its MCP server
  155. - `src/context_ledger/` is the CLP library
  156. ## Roadmap
  157. - measure Claude against GPT on the routing benchmark, and only then let auto-routing choose between them
  158. - more real use on Linux, including account switching without the macOS Keychain
  159. - let auto-routing consider newly discovered Claude model aliases
  160. - bring the lab status line to Codex sessions
  161. ## Contributing
  162. Bug reports and pull requests are welcome. [CONTRIBUTING.md](CONTRIBUTING.md) covers running the tests, and [SECURITY.md](SECURITY.md) says how to report a vulnerability privately. If Alnair is useful to you, a star helps other people find it.
  163. MIT licensed. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.