Skip to content
Back to search

llm-wiki-autopilot

MarketplaceWorks with Claude CodeGitHub

Andrej Karpathy's LLM Wiki pattern on autopilot: every Claude Code & Codex session is written into an Obsidian wiki automatically. Git sync across machines, project context at session start, time-tracking dashboard. Zero dependencies.

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/yusufkaran--karpathy-llm-wiki-autopilot/badge.svg)](/listings/yusufkaran--karpathy-llm-wiki-autopilot)

HTML

<a href="/listings/yusufkaran--karpathy-llm-wiki-autopilot"><img src="/api/listings/yusufkaran--karpathy-llm-wiki-autopilot/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

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

git clone https://github.com/yusufkaran/karpathy-llm-wiki-autopilot ~/.vault-memory/src
~/.vault-memory/src/install.sh --vault ~/Vault --lang en --timer

The installer:

1. Creates the vault from the template if the folder is not a vault yet (no `CLAUDE.md`), and runs `git init`. A new, empty folder is the safe choice. 2. Copies the CLI, the dashboard and the skill into `<vault>/99-Meta/System/`. 3. Writes `~/.vault-memory/config.json` and links `~/.vault-memory/bin` to the vault's copy of the CLI. 4. Adds `SessionStart`, `Stop` and `SessionEnd` hooks to `~/.claude/settings.json` (after backing it up). 5. Installs the skill into `~/.claude/skills/`. 6. Marks existing transcripts as already processed, so nothing is imported by surprise. 7. With `--timer`, installs a 5-minute timer (launchd on macOS, a systemd user timer on Linux).

| Flag | Meaning | |---|---| | `--vault PATH` | Vault folder (created if needed) | | `--lang en\|tr` | Language of the vault pages; kept on later runs | | `--machine NAME` | Name of this machine in session files (default: host name) | | `--remote URL` | Git remote to push the vault to | | `--timer` | Install the 5-minute background timer | | `--dashboard` | Start the dashboard at login | | `--no-hooks` | Don't touch `~/.claude/settings.json` | | `--no-skill` | Don't install the skill (e.g. when it comes from the plugin) |

The CLI is `vm`, installed in `~/.vault-memory/bin` (add that folder to your `PATH` to type just `vm`). Open the vault folder in Obsidian if you like; it already has templates, a sessions table view and daily notes set up.

To import past sessions, queue them and let the worker run (one LLM call per session):

~/.vault-memory/bin/vm backfill --days 14 --dry-run   # see what would be queued
~/.vault-memory/bin/vm backfill --days 14
~/.vault-memory/bin/vm worker --max 500

Sync with a private remote

~/.vault-memory/src/install.sh --vault ~/Vault --lang en --timer --remote git@github.com:you/my-vault.git

Use a **private** repository. The vault holds summaries of everything you work on.

Add another machine

git clone git@github.com:you/my-vault.git ~/Vault
~/Vault/99-Meta/System/bin/vm install --machine server --timer

The tool lives inside the vault, so every machine runs the version that was last synced. On a laptop that is often closed, turn on `vm config capture true`; on an always-on machine, `vm config process_remote true` (see [Several machines](#several-machines)).

Install as a Claude Code plugin

/plugin marketplace add yusufkaran/karpathy-llm-wiki-autopilot
/plugin install llm-wiki-autopilot@llm-wiki-autopilot

Then ask Claude to "set up vault memory". The skill asks where the vault should live, which language to use and whether to sync with a remote, then runs the installer with `--no-skill`. The plugin ships the skill in English (`vault-memory`) and Turkish (`vault-hafiza`).

Without the plugin system: `npx skills add yusufkaran/karpathy-llm-wiki-autopilot --skill vault-memory` (or `--skill vault-hafiza` for Turkish).

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.

.claude-plugin/marketplace.json · Manifest · 36 lines
  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "llm-wiki-autopilot",
  4. "owner": {
  5. "name": "Yusuf Karan",
  6. "url": "https://github.com/yusufkaran"
  7. },
  8. "metadata": {
  9. "description": "Persistent memory for coding agents: Claude Code and Codex sessions distilled into an Obsidian vault, synced with git, with a local time dashboard.",
  10. "version": "1.0.0"
  11. },
  12. "plugins": [
  13. {
  14. "name": "llm-wiki-autopilot",
  15. "source": "./",
  16. "description": "Skills to set up, query and maintain an Obsidian vault that your Claude Code and Codex sessions are written into automatically (Karpathy's LLM Wiki pattern), plus per-project time reports and a local dashboard.",
  17. "version": "1.0.0",
  18. "author": {
  19. "name": "Yusuf Karan",
  20. "url": "https://github.com/yusufkaran"
  21. },
  22. "category": "productivity",
  23. "homepage": "https://github.com/yusufkaran/karpathy-llm-wiki-autopilot",
  24. "keywords": [
  25. "obsidian",
  26. "memory",
  27. "llm-wiki",
  28. "knowledge-base",
  29. "time-tracking",
  30. "dashboard",
  31. "codex",
  32. "git-sync"
  33. ]
  34. }
  35. ]
  36. }
README.md · README · 339 lines
  1. # LLM Wiki Autopilot
  2. **Andrej Karpathy's LLM Wiki pattern, on autopilot: persistent memory for Claude Code and Codex, written into
  3. Obsidian automatically.**
  4. Every coding-agent session you finish becomes part of a wiki: a dated session log, a living page per project,
  5. decisions and lessons, with no "save this" prompts and no manual notes. The wiki is plain Markdown in a git repository, so it syncs across your machines, and every new
  6. Claude Code session starts with the project's current status already in context. A local dashboard shows where
  7. your time went.
  8. [![test](https://github.com/yusufkaran/karpathy-llm-wiki-autopilot/actions/workflows/test.yml/badge.svg)](https://github.com/yusufkaran/karpathy-llm-wiki-autopilot/actions/workflows/test.yml)
  9. ![License: MIT](https://img.shields.io/badge/license-MIT-blue)
  10. ![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)
  11. ![macOS | Linux](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey)
  12. ![No dependencies](https://img.shields.io/badge/dependencies-none-brightgreen)
  13. English | [Türkçe](README.tr.md)
  14. <picture>
  15. <source media="(prefers-color-scheme: dark)" srcset="docs/dashboard-dark.png">
  16. <img alt="Dashboard" src="docs/dashboard.png">
  17. </picture>
  18. ## Features
  19. - **Runs by itself.** Claude Code hooks and a 5-minute timer pick up every finished session. Nothing to remember.
  20. - **Session log.** Each session becomes an entry in a per-project, per-day file: what was asked, what was done,
  21. decisions and open items. Trivial sessions get a one-line entry.
  22. - **Living project pages.** Status, open items, decisions and "good to know" are rewritten after every session.
  23. Architecture decision records, topic pages and tool pages are opened when a session warrants them.
  24. - **Memory at session start.** A `SessionStart` hook gives every new Claude Code session the project's status,
  25. open items and last five sessions. Agents without hooks, such as Codex, can print the same text with `vm context`.
  26. - **Time tracking.** Active minutes per project and day: `vm report` in the terminal, a local dashboard with charts.
  27. - **Several machines, one memory.** Git sync with a shared ledger, so no session is processed twice. A laptop that
  28. was closed mid-session can hand its last session to an always-on machine.
  29. - **Source ingest.** Drop an article or PDF into `00-Inbox/` or `05-Raw/clippings/`; `vm ingest` writes a summary
  30. page and updates the pages it touches.
  31. - **Health check.** `vm lint` finds broken links, orphan pages and missing frontmatter.
  32. - **Safe by default.** Secrets are redacted before anything reaches the model, commits that contain a secret are
  33. blocked, and the background agent cannot change its own code, config or instruction files.
  34. - **Light.** One Python file using only the standard library. No database, no always-on daemon.
  35. - **English or Turkish** vault pages, CLI output and dashboard.
  36. ## Requirements
  37. - macOS or Linux
  38. - Python 3.9+ and git
  39. - [Claude Code](https://docs.claude.com/en/docs/claude-code) CLI, logged in (the worker runs `claude -p`)
  40. - Optional: Codex CLI (its sessions are processed too), Obsidian (to browse the vault)
  41. ## Quick start
  42. ```bash
  43. git clone https://github.com/yusufkaran/karpathy-llm-wiki-autopilot ~/.vault-memory/src
  44. ~/.vault-memory/src/install.sh --vault ~/Vault --lang en --timer
  45. ```
  46. The installer:
  47. 1. Creates the vault from the template if the folder is not a vault yet (no `CLAUDE.md`), and runs `git init`.
  48. A new, empty folder is the safe choice.
  49. 2. Copies the CLI, the dashboard and the skill into `<vault>/99-Meta/System/`.
  50. 3. Writes `~/.vault-memory/config.json` and links `~/.vault-memory/bin` to the vault's copy of the CLI.
  51. 4. Adds `SessionStart`, `Stop` and `SessionEnd` hooks to `~/.claude/settings.json` (after backing it up).
  52. 5. Installs the skill into `~/.claude/skills/`.
  53. 6. Marks existing transcripts as already processed, so nothing is imported by surprise.
  54. 7. With `--timer`, installs a 5-minute timer (launchd on macOS, a systemd user timer on Linux).
  55. | Flag | Meaning |
  56. |---|---|
  57. | `--vault PATH` | Vault folder (created if needed) |
  58. | `--lang en\|tr` | Language of the vault pages; kept on later runs |
  59. | `--machine NAME` | Name of this machine in session files (default: host name) |
  60. | `--remote URL` | Git remote to push the vault to |
  61. | `--timer` | Install the 5-minute background timer |
  62. | `--dashboard` | Start the dashboard at login |
  63. | `--no-hooks` | Don't touch `~/.claude/settings.json` |
  64. | `--no-skill` | Don't install the skill (e.g. when it comes from the plugin) |
  65. The CLI is `vm`, installed in `~/.vault-memory/bin` (add that folder to your `PATH` to type just `vm`).
  66. Open the vault folder in Obsidian if you like; it already has templates, a sessions table view and daily notes set up.
  67. To import past sessions, queue them and let the worker run (one LLM call per session):
  68. ```bash
  69. ~/.vault-memory/bin/vm backfill --days 14 --dry-run # see what would be queued
  70. ~/.vault-memory/bin/vm backfill --days 14
  71. ~/.vault-memory/bin/vm worker --max 500
  72. ```
  73. ### Sync with a private remote
  74. ```bash
  75. ~/.vault-memory/src/install.sh --vault ~/Vault --lang en --timer --remote git@github.com:you/my-vault.git
  76. ```
  77. Use a **private** repository. The vault holds summaries of everything you work on.
  78. ### Add another machine
  79. ```bash
  80. git clone git@github.com:you/my-vault.git ~/Vault
  81. ~/Vault/99-Meta/System/bin/vm install --machine server --timer
  82. ```
  83. The tool lives inside the vault, so every machine runs the version that was last synced. On a laptop that is
  84. often closed, turn on `vm config capture true`; on an always-on machine, `vm config process_remote true`
  85. (see [Several machines](#several-machines)).
  86. ### Install as a Claude Code plugin
  87. ```
  88. /plugin marketplace add yusufkaran/karpathy-llm-wiki-autopilot
  89. /plugin install llm-wiki-autopilot@llm-wiki-autopilot
  90. ```
  91. Then ask Claude to "set up vault memory". The skill asks where the vault should live, which language to use and
  92. whether to sync with a remote, then runs the installer with `--no-skill`. The plugin ships the skill in English
  93. (`vault-memory`) and Turkish (`vault-hafiza`).
  94. Without the plugin system: `npx skills add yusufkaran/karpathy-llm-wiki-autopilot --skill vault-memory`
  95. (or `--skill vault-hafiza` for Turkish).
  96. ## How it works
  97. ```
  98. Claude Code / Codex transcripts (~/.claude/projects, ~/.codex/sessions)
  99. │ session idle for 20 min; a hook or the 5-minute timer starts the worker
  100. ▼
  101. vm worker builds a digest: messages, tool calls, changed files; secrets redacted
  102. │
  103. ▼
  104. claude -p tools limited to Read/Glob/Grep/Edit/Write; appends the session entry,
  105. │ updates the project page, opens ADRs and topic pages when warranted
  106. ▼
  107. git commit + push ──► your private remote ──► other machines pull
  108. (SessionStart hook, timer)
  109. ```
  110. ## Dashboard
  111. ```bash
  112. ~/.vault-memory/bin/vm dashboard # http://127.0.0.1:4747
  113. ```
  114. - Total time with the change against the previous period of the same length, active days, busiest day.
  115. - Daily columns stacked by project (weekly for long ranges), per-project bars, weekday × hour heatmap.
  116. - Splits by machine, tool, and weekday vs weekend; a session-length histogram; a sortable project table.
  117. - A searchable session list with each session's request, work done, decisions and open items, linked to Obsidian.
  118. - Filters for date range, project, machine and tool; light and dark themes; English and Turkish.
  119. It reads the vault on every refresh and changes nothing. Options: `--port`, `--host`, `--no-open`.
  120. `vm install --dashboard` starts it at login. To try it with sample data: `python3 system/dashboard/server.py --demo`.
  121. ## Commands
  122. | Command | What it does |
  123. |---|---|
  124. | `vm worker [--now] [--session ID] [--sync] [--max N]` | Process finished sessions, commit, push |
  125. | `vm tick` | Timer entry point: `capture`, then `worker` |
  126. | `vm hook session-start\|session-end\|stop` | Claude Code hook entry point |
  127. | `vm report [--project P] [--from D --to D \| --days N \| --week this\|last] [--detail] [--json]` | Time per project and day |
  128. | `vm status [--json]` | Queue, alert, last log lines |
  129. | `vm dashboard [--host H] [--port N] [--no-open]` | Local dashboard |
  130. | `vm sync` | Pull, commit, push |
  131. | `vm index` | Regenerate `index.md` |
  132. | `vm lint` | Write a health report to `99-Meta/Lint/` |
  133. | `vm context [--cwd DIR]` | Print the project memory for a folder (for agents without hooks, like Codex) |
  134. | `vm ingest [--now] [--path P] [--dry-run]` | Process new files in the inbox folders |
  135. | `vm backfill --days N [--project P] [--exclude X] [--dry-run]` | Queue sessions from before installation |
  136. | `vm baseline [--force]` | Mark all existing transcripts as processed |
  137. | `vm digest PATH [--offset N] [--show]` | Show the digest of a transcript (debugging) |
  138. | `vm config [KEY [VALUE]]` | Show or change this machine's settings |
  139. | `vm install [--machine NAME] [--timer] [--dashboard] [--no-hooks] [--no-skill]` | Set up this machine |
  140. | `vm uninstall [--keep-skill]` | Remove hooks, timer, dashboard service and skill from this machine |
  141. ## Configuration
  142. Settings come from two files. Per-machine values override shared ones.
  143. - **Shared:** `<vault>/99-Meta/System/config.json`, synced with the vault.
  144. - **This machine:** `~/.vault-memory/config.json`, changed with `vm config KEY VALUE`.
  145. | Key | Default | Usually set in | Meaning |
  146. |---|---|---|---|
  147. | `language` | `en` | shared | Language of vault pages and CLI output (`en`, `tr`) |
  148. | `timezone` | system | shared | IANA name used for dates and times, e.g. `Europe/Berlin` |
  149. | `idle_minutes` | `20` | shared | A session is processed after this long without new messages |
  150. | `gap_cap_minutes` | `5` | shared | Longest gap between two messages that still counts as active time |
  151. | `model` | `sonnet` | shared | Model the worker uses |
  152. | `effort` | `medium` | shared | Reasoning effort for the worker |
  153. | `max_budget_usd` | `2.0` | shared | Spending cap per worker call |
  154. | `max_per_run` | `6` | shared | Session entries processed per worker run |
  155. | `sources` | `["claude", "codex"]` | shared | Which agents' transcripts to read |
  156. | `projects_roots` | `~/Projects`, `~/projects`, `~/code`, `~/dev`, `~/src`, `~/work`, … | shared | Folders whose direct subfolders are projects |
  157. | `ingest_dirs` | `00-Inbox`, `05-Raw/clippings`, `05-Raw/files` | shared | Folders `vm ingest` watches |
  158. | `vault` | – | machine | Path of the vault |
  159. | `machine` | host name | machine | Machine name used in file names |
  160. | `claude_bin` | `claude` | machine | Path of the Claude Code CLI |
  161. | `capture` | `false` | machine | Push redacted digests of unprocessed sessions to `outbox/<machine>` |
  162. | `process_remote` | `false` | machine | Process other machines' outbox packets they left unprocessed |
  163. ## How time is measured
  164. Time is active time with an agent. For each session the gaps between consecutive messages are added up, and
  165. each gap counts for at most `gap_cap_minutes` (5 by default), so lunch breaks and idle windows don't count. Time
  166. spent without an agent is not counted. Two sessions running at the same time are both counted, so a day can
  167. add up to more than the hours on the clock.
  168. ## Privacy and safety
  169. - Everything runs on your machines. Transcripts are never copied anywhere. What leaves the machine is the
  170. redacted digest sent to Claude through your own CLI login and, only with `capture` on, the same digest pushed
  171. to the `outbox/<machine>` branch of your own git remote.
  172. - Known secret patterns (API keys, tokens, private keys, passwords in `key=value` form, credentials in URLs) are
  173. redacted in digests. If a value in a known key format still ends up in a vault change, the commit is blocked
  174. and `vm status` shows an alert until you remove it.
  175. - The worker runs `claude -p` with only Read, Glob, Grep, Edit and Write, no Bash, no MCP servers, hooks
  176. disabled, and a per-call budget cap. It works inside the vault folder and runs no git commands; the script
  177. commits.
  178. - The worker reads untrusted text (session digests, web clippings), so what it may change is enforced in code,
  179. not only in its instructions. Before each call the protected paths are snapshotted: `99-Meta/` (the tool, the
  180. shared config, templates), `index.md`, `log.md`, agent instruction files such as `CLAUDE.md` and `AGENTS.md` at
  181. any depth and in any letter case, every dot file and dot folder at any depth (`.claude/`, `.obsidian/` plugins, …)
  182. and the git metadata in `.git`. Any change to them is reverted
  183. before the commit, and `vm status` shows an alert. Injected text can still shape what the worker writes into
  184. ordinary pages, so review sources you ingest from the web.
  185. - `claude_bin`, `path`, `setting_sources`, `capture` and `process_remote` are read only from the per-machine
  186. config; the shared config in the vault cannot set them.
  187. - The dashboard binds to `127.0.0.1` and only reads.
  188. ## Resource use
  189. Measured on a Mac with 258 transcripts (2.6 GB, the largest 330 MB):
  190. - The timer and the after-reply hook start a short Python process (about 30 MB, 0.1 s) and exit. Finding pending
  191. sessions takes 0.02 s; transcripts are read as a stream, so even a 330 MB file stays near 100 MB of memory.
  192. - Background work runs at low priority (`nice 10`; on macOS the timer is a `Background` launchd job with low-priority
  193. I/O, on Linux `IOSchedulingClass=idle`).
  194. - After an agent reply, digests are pushed at most once a minute (`capture_interval_seconds`).
  195. - The heaviest step is the `claude -p` call itself, once per finished session, one at a time.
  196. - The dashboard server idles at about 30 MB and 0% CPU; the page polls once a minute, only while its tab is
  197. visible, and redraws only when something changed. No GPU work beyond normal page rendering.
  198. ## Cost
  199. Each finished session with real content is one `claude -p` call, with `sonnet` by default and capped at
  200. `max_budget_usd` per call. Short sessions (a greeting, a one-line question) are logged without a call.
  201. `vm backfill` makes one call per queued session, so try `--dry-run` first.
  202. ## Project mapping
  203. - A folder directly under one of the `projects_roots` is one project, including every git repository inside it.
  204. - A git repository outside those roots is a project named after its folder.
  205. - Anything else (home folder, temp folders, `~/.claude`) belongs to no project and goes to
  206. `05-Raw/sessions/` as `general`.
  207. - A session is matched to a project page by the git remote in the page's `repos` field first, then by the folder
  208. name in `folders`. The worker adds new remotes and folders there. To merge two folders into one project, add
  209. the second folder's name (or its remote) to the first project's `folders` (or `repos`).
  210. ## Several machines
  211. - Each machine processes its own sessions and appends `machine session offset` lines to
  212. `99-Meta/System/processed.txt`. The ledger travels with the vault, so no session is processed twice.
  213. - With `capture` on, a machine pushes redacted digests of its unprocessed sessions to the `outbox/<machine>`
  214. branch after every agent reply. The branch is overwritten each time and never enters `main`.
  215. - With `process_remote` on, a machine processes those packets if their owner hasn't done so within
  216. `remote_idle_minutes` (30), and records them under the owner's name. A laptop closed mid-session still gets
  217. its last session into the vault.
  218. - On a push conflict, the local work is saved to a backup branch, the machine returns to the remote state, and
  219. the affected sessions are processed again.
  220. ## Upgrading
  221. ```bash
  222. git -C ~/.vault-memory/src pull --ff-only
  223. ~/.vault-memory/src/install.sh --vault ~/Vault
  224. ~/.vault-memory/bin/vm sync
  225. ```
  226. The installer copies the new CLI, dashboard and skill into the vault and keeps your language and settings.
  227. `vm sync` pushes them; other machines run the new version after their next pull.
  228. ## Uninstall
  229. ```bash
  230. ~/.vault-memory/bin/vm uninstall
  231. ```
  232. Removes the hooks, timer, dashboard service and skill from this machine. Your vault is left as it is.
  233. ## Troubleshooting
  234. - `vm status` shows the queue, the last worker log lines and any alert. The full log is
  235. `~/.vault-memory/logs/worker.log`.
  236. - **Commit blocked by a secret:** run `git status` in the vault, remove the value from the changed file, run `vm sync`.
  237. - **Sync conflict:** run `git pull --rebase` in the vault, resolve the file, run `vm sync`.
  238. - **Nothing gets processed:** check that `claude` runs from a non-interactive shell (`vm config claude_bin`),
  239. that the timer is installed (`vm install --timer`), and that the session has been idle for `idle_minutes`.
  240. `vm worker --now` skips the wait.
  241. - **A session landed in the wrong project:** fix `repos` / `folders` on the project pages; later sessions follow.
  242. ## FAQ
  243. **Do I need Obsidian?** No. The vault is a folder of Markdown files in git; Obsidian is just a good way to read it
  244. (templates, a sessions table and daily notes are set up for it).
  245. **Does my code or my transcripts leave the machine?** Only a redacted digest of each session goes to Claude, through
  246. your own Claude Code login, and the resulting pages go to the git remote you choose. See
  247. [Privacy and safety](#privacy-and-safety).
  248. **Which agents are supported?** Claude Code and the Codex CLI: their transcripts are read from `~/.claude/projects`
  249. and `~/.codex/sessions`. Session-start memory is automatic in Claude Code; other agents can call `vm context`.
  250. **What does it cost?** One `claude -p` call per finished session that has real content. See [Cost](#cost).
  251. **Can I import my old sessions?** Yes, with `vm backfill --days N`; see [Quick start](#quick-start).
  252. ## Repository layout
  253. ```
  254. install.sh creates or upgrades a vault and sets up this machine
  255. system/bin/ vm and vault_memory.py (copied into <vault>/99-Meta/System/bin)
  256. system/dashboard/ server.py and index.html
  257. skills/ vault-memory (English) and vault-hafiza (Turkish) skills
  258. template/ vault skeleton: common files plus en/ and tr/ rules and page templates
  259. docs/SPEC.md file formats, CLI and dashboard API
  260. tests/ tests (they use a fake LLM; no API calls)
  261. ```
  262. ## Credits
  263. The vault model follows Andrej Karpathy's "LLM Wiki" idea: an LLM that maintains a wiki from the sources you
  264. give it, instead of answering from scratch every time. This is an independent project; it is not affiliated with
  265. or endorsed by Andrej Karpathy.
  266. ## License
  267. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

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