Byblos

Byblos is a local-first context wiki for LLM agents. It lets Codex read your personal and project context through MCP, draft safe wiki updates, and apply only approved changes.

Byblos is designed for people who repeatedly need agents to remember preferences, project rules, decisions, workflows, references, and reusable answers without pasting the same context into every prompt.

Why

LLM agents are more useful when they can read stable context, but context should not be copied into every prompt or silently rewritten by the agent. Byblos provides a filesystem-backed wiki, a CLI, and a Codex plugin so agents can discover context, read original documents, and propose guarded writes.

Byblos keeps a clear boundary:

• agents search context before answering;
• search results include original path, hash, scope, status, and category;
• important answers can require full-document reads, not snippets only;
• new knowledge is drafted as a candidate change first;
• accepted writes require validation and explicit approval;
• personal context stays under ~/.byblos/context by default;
• project context is opt-in through .byblos/context or a configured external path.

Features

• CLI for setup, context resolution, wiki search/read/lint, source ingest, change approval, rollback, and git sync.
• Codex plugin with MCP server, skills, and subagent guides.
• MCP tools for original context access: search_context, read_context_doc, read_context_range, and get_relevant_context.
• Guarded write workflow: draft, validate, approve, apply, rollback.
• Source ingest that preserves raw input, extracted text, metadata, and candidate wiki pages.
• Secret-like content hard blocks that normal --yes approval cannot bypass.
• Project-first context resolution with personal fallback.
• Optional git sync for personal or external context repositories.

Install

Install Byblos globally with npm:

npm install -g byblos
byblos setup codex --yes
byblos context init --scope personal
byblos doctor --json

Or use the curl installer:

curl -fsSL https://raw.githubusercontent.com/crispebble/byblos/main/install.sh | sh

The curl installer checks Node.js and npm, installs the byblos npm package globally, installs the Codex plugin asset, initializes personal context if needed, and runs byblos doctor --json.

byblos setup codex --yes installs the Codex plugin asset to ~/.codex/plugins/byblos and merges the local plugin entry into ~/.agents/plugins/marketplace.json.

Quick Start

Check installation and resolved context:

byblos doctor --json
byblos context status --json

Search your context:

byblos wiki search "deployment preferences" --json

Read a full context document before making a final judgment:

byblos wiki read <doc-id-or-path> --json

Ingest a local note as a guarded draft:

byblos source ingest ./note.md --title "Project Note" --category references --json

Review and apply a change:

byblos change list --json
byblos change show <change-id> --json
byblos change validate <change-id> --json
byblos change apply <change-id> --yes --json

Lint the wiki:

byblos wiki lint --json

CLI

Common commands:

byblos doctor --json
byblos setup codex --yes
byblos context init --scope personal
byblos context init --scope project
byblos context resolve --json
byblos context status --json
byblos context use <path> --scope personal --yes
byblos context use <path> --scope project --yes
byblos wiki search "query" --json
byblos wiki read <doc-id-or-path> --json
byblos wiki lint --json
byblos source ingest <path> --title "Title" --category references --json
byblos source status --json
byblos change list --json
byblos change show <change-id> --json
byblos change apply <change-id> --yes --json
byblos change rollback <change-id> --yes --json
byblos git status --json
byblos git sync --dry-run --json
byblos mcp serve

--cwd <path> controls project discovery and relative path resolution. If omitted, Byblos uses the current shell location.

byblos context status --cwd /path/to/project --json
byblos context init --scope project --cwd /path/to/project --json
byblos source ingest ./note.md --cwd /path/to/project --json

Relative --context, source paths, and body files are resolved from --cwd.

Codex Plugin

The Codex plugin includes:

• MCP server: byblos mcp serve
• Skills: context-based answering, ingest, maintenance, setup
• Subagents: setup, reviewer, ingest, maintainer, sync

Representative MCP tools:

• search_context: discover matching context documents.
• read_context_doc: read an original context document in full.
• read_context_range: read a line range or heading range.
• get_relevant_context: collect original context chunks for multiple query items.
• get_llm_wiki_prompt: read Byblos workflow and adapter prompts.
• draft_context_change: create a guarded change draft.
• apply_context_change: apply a validated and approved change.
• record_secret_override: record a separate high-risk override for secret hard blocks.
• rollback_context_change: rollback an applied change from its snapshot.
• ingest_source: draft raw, extracted, metadata, and wiki targets from a source file.
• lint_wiki: validate wiki structure and page conventions.

Context Layout

Default personal context:

~/.byblos/context

Default project context:

<project-root>/.byblos/context

External context paths can be configured:

byblos context use <path> --scope personal --yes
byblos context use <path> --scope project --yes

Resolution order:

explicit --context <path>
project context from --cwd/current project
personal context from ~/.byblos/context

Project context wins over personal context when both are valid. Personal context is used as fallback for reusable user preferences and cross-project knowledge.

Safety And Privacy

• Byblos runtime state and personal config live under ~/.byblos/.
• Project context is created only when requested.
• generated/ files are disposable artifacts, not source of truth.
• Accepted wiki writes are applied through guarded change bundles.
• Secret-like content creates a hard block. Normal --yes approval is not enough to bypass it.
• Do not store private tokens, credentials, customer data, or company-sensitive raw content in a public repo.

Development

Source is TypeScript under src/*.ts. The project uses strict: true.

npm install
npm run typecheck
npm run build
npm test
npm run smoke
npm pack --dry-run

Runtime output is generated into dist/. Test output is generated into dist-test/ and is not included in the npm package.

License

MIT