A CLI tool for LLM agents to build and maintain personal knowledge bases.
Inspired by Andrej Karpathy's LLM Wiki.
Live Demo — interactive d3-force graph built from the example wiki in test-wiki-page/.
The CLI is the hands -- it reads, writes, searches, and manages wiki files. The LLM is the brain -- it decides what to create, update, and connect.
LLM Agent (Claude Code / Codex)
|
| shells out to:
| $ wiki init my-wiki --domain "machine learning"
| $ wiki write wiki/concepts/attention.md <<'EOF' ... EOF
| $ wiki index add "concepts/attention.md" "Overview of attention"
| $ wiki search "scaling laws"
| $ wiki lint
|
v
wiki CLI (StorageProvider abstraction)
|
v
filesystem | git (auto-commit + auto-push)
Key principle: The CLI never calls any LLM API. It is a pure storage tool with pluggable backends.
npm install -g llmwiki-cliThis gives you two commands: wiki (primary, 4 chars) and llmwiki (fallback if wiki conflicts).
| Backend | Description | Init |
|---|---|---|
filesystem (default) |
Plain markdown files on disk | wiki init my-wiki |
git |
Filesystem + auto-commit + auto-push to GitHub | wiki init my-wiki --backend git --git-token <pat> |
# Create a new wiki (filesystem backend, default)
wiki init my-wiki --name "My Notes" --domain "research"
# Or with git + GitHub sync
wiki init my-wiki --name "My Notes" --domain "research" --backend git --git-token ghp_xxx
# Write a page
wiki write wiki/concepts/attention.md <<'EOF'
---
title: Attention Mechanism
created: 2025-01-20
tags: [transformers, NLP]
---
The attention mechanism allows models to focus on relevant parts of the input.
See also [[transformers]] and [[self-attention]].
EOF
# Add to index and log
wiki index add "concepts/attention.md" "Overview of attention mechanisms"
wiki log append ingest "Attention mechanism page"
# Search and lint
wiki search "attention"
wiki lintWhen you run wiki init (filesystem or git backend), it creates:
my-wiki/
├── .git/ # Only with --backend git
├── .github/ # Only with --backend git (--viz)
│ └── workflows/
│ └── wiki-viz.yml # GitHub Actions → GitHub Pages visualization
├── .gitignore # Only with --backend git (--viz)
├── .llmwiki.yaml # Wiki config (all backends)
├── SCHEMA.md # Instructions for LLM agents
├── scripts/ # Only with --backend git (--viz)
│ ├── build-graph.js # Builds graph.json from wikilinks
│ └── build-site.js # Generates d3-force visualization
├── raw/ # Immutable source documents
│ └── assets/ # Downloaded images
└── wiki/ # LLM-generated pages
├── index.md # Master index of all pages
├── log.md # Chronological activity log
├── entities/ # People, orgs, products
├── concepts/ # Ideas, frameworks, theories
├── sources/ # One summary per ingested source
└── synthesis/ # Cross-cutting analysis
Storage profiles: wiki profile use <slug>, --profile, LLMWIKI_PROFILE, or top-level profile in .llmwiki.yaml. Pages live under profiles/<slug>/ inside the wiki directory. This is organizational separation only, not OS or cryptographic isolation.
wiki init [dir] --name <name> --domain <domain> --backend <type>
wiki init [dir] --backend git --git-token <pat> [--git-repo owner/repo]
wiki init [dir] --backend git --no-viz # Skip visualization scaffolding
wiki init [existing-wiki-dir] --viz # Add visualization to existing git wiki
wiki registry # List all wikis
wiki use [wiki-id] # Set active wiki
wiki profile show # Effective storage root and profile
wiki profile use <slug> # Save profile in registry
wiki profile clear # Remove saved profilewiki read <path> # Print page to stdout
wiki write <path> # Write stdin to page
wiki append <path> # Append stdin to page
wiki list [dir] [--tree] [--json] # List pages
wiki search <query> [--limit N] [--all] [--json] # Search pageswiki index show # Print master index
wiki index add <path> <summary> # Add entry to index
wiki index remove <path> # Remove entry
wiki log show [--last N] [--type T] # Print log entries
wiki log append <type> <message> # Append log entrywiki lint [--json] # Health check
wiki links <path> # Outbound + inbound links
wiki backlinks <path> # Inbound links only
wiki orphans # Pages with no inbound links
wiki status [--json] # Wiki overview statsRun wiki skill to print the full guide, or see docs/SKILL.md for the source. Covers workflows, command patterns, page format, and common gotchas for LLM agents.
The generated SCHEMA.md in each wiki contains complete instructions. Here are the typical workflows:
# Save raw source
wiki write raw/paper.md <<'EOF'
<paste full text of paper>
EOF
# Create structured summary
wiki write wiki/sources/attention-paper.md <<'EOF'
---
title: Attention Is All You Need
created: 2025-01-20
tags: [transformers, attention, NLP]
source: https://arxiv.org/abs/1706.03762
---
Summary of the attention paper...
Links to [[transformers]] and [[self-attention]].
EOF
# Update bookkeeping
wiki index add "sources/attention-paper.md" "Attention Is All You Need (2017)"
wiki log append ingest "Attention paper"wiki search "attention mechanism"
wiki read wiki/concepts/attention.md
wiki links wiki/concepts/attention.md # see related pages
wiki log append query "How does multi-head attention work?"wiki lint # find broken links, orphans, missing frontmatter
wiki orphans # pages nobody links to
wiki status # overview stats- New repo: With
--git-tokenand no--git-repo, the CLI createswiki-<name>as a public repository (straightforward to try GitHub Pages). Use--git-repo owner/existingto target a repo you already manage. - Token not committed:
.llmwiki.yamlstoresgit.repoonly, not your PAT, so GitHub’s push secret scanning does not reject commits. Forwiki write/wiki append(auto-push), setLLMWIKI_GIT_TOKEN,GITHUB_TOKEN, orGIT_TOKENin your environment. - PAT permissions: The token must be allowed to update GitHub Actions workflow files (classic PAT: include the
workflowscope; fine-grained: grant workflow/Actions write). Otherwise the first push after init can fail on.github/workflows/wiki-viz.yml.
Git-backend wikis automatically include a GitHub Actions workflow that builds an interactive d3-force graph visualization of your wiki's link structure and deploys it to GitHub Pages.
- Auto-scaffolded:
wiki init --backend gitcreates.github/workflows/wiki-viz.ymlandscripts/build scripts by default - On every push: GitHub Actions parses all
[[wikilinks]], builds a force-directed graph, and deploys to Pages - Interactive: color-coded nodes by directory, zoom/pan, click-to-highlight connections, hover tooltips
- Opt-out: use
--no-vizto skip visualization scaffolding - Add to existing wiki: re-run
wiki init <dir> --vizon an existing git wiki to add visualization files
After a successful first push, init also tries to enable GitHub Pages (build: GitHub Actions). You can still configure it under Settings → Pages → Source: GitHub Actions if needed.
Branch name: New git wikis rename the default branch to main before the first push so the github-pages Actions environment (which often only allows main) accepts deployment. If you see “Branch master is not allowed to deploy to github-pages”, rename locally with git branch -M main, push main, and under Settings → General set the default branch to main (and optionally delete the old master branch on GitHub).
The CLI supports multiple wikis via a global registry at ~/.config/llmwiki/:
wiki init ~/wikis/ml --name ml --domain "machine learning"
wiki init ~/wikis/personal --name personal --domain "personal notes"
wiki registry # lists both
wiki use ml # switch active wiki
wiki --wiki personal read wiki/index.md # target specific wiki
wiki search "neural networks" --all # search across all wikisWiki resolution order: --wiki flag > cwd .llmwiki.yaml > walk up directories > registry default.
- Node.js >= 18 (or Bun)
- Git (for
--backend gitonly)
git clone https://github.com/doum1004/llmwiki-cli
cd llmwiki-cli
bun install
bun test # 194 tests
bun run build # bundle to dist/wiki.js
bun run dev -- --helpMIT