Codebase Wiki

Architectural knowledge base with MCP interface for AI agents.

Agents discover services, generate LLM-powered docs with Mermaid C2/C3/sequence diagrams, and index them for semantic search. Includes self-learning notes and first-class workflow/flow indexing.

Quick Start

npm install -g @carreira-cloud/codebase-wiki

cd my-project
codebase-wiki init              # Initialize knowledge base
codebase-wiki serve             # Browse at http://localhost:3080
codebase-wiki start-mcp         # Start MCP server for AI agents

Commands

Command	Description
`init`	Initialize knowledge base for current repo
`serve`	Start web UI (markdown + mermaid rendering, flows tab)
`start-mcp`	Start MCP server (stdio JSON-RPC, 12 tools)
`search <query>`	Search docs, notes, and flows by keyword
`get <service>`	Retrieve full documentation for a service
`list`	List all indexed services
`stats`	Statistics: services, flows, notes, content size
`install-opencode`	Install OpenCode skills and commands

MCP Tools

Documentation (8 tools)

Tool	Description
`wiki_index`	Index an LLM-generated architectural document
`wiki_search`	Search documentation by keyword
`wiki_get`	Retrieve full documentation for a service
`wiki_list`	List all indexed services
`wiki_delete`	Remove a service's documentation
`wiki_stats`	Statistics: services, content size, notes count, flows count

Self-Learning Notes (3 tools)

Tool	Description
`wiki_note`	Store a self-learning discovery note
`wiki_notes_search`	Search agent notes by keyword
`wiki_notes_list`	List notes (optional type filter)

Workflows & Flows (3 tools)

Tool	Description
`wiki_flow_index`	Index a workflow diagram with keywords and linked services
`wiki_flow_search`	Search flows across all services by keyword
`wiki_flow_list`	List flows (optional service/flow_type filter)

OpenCode Commands

/wiki generate <service>       → Agent discovers, generates docs, indexes via MCP
/wiki generate-all              → Generate docs for all services
/wiki enhance <service> <flow>  → Add Mermaid C3/C2/sequence diagrams
/wiki discover-flows <service>  → Discover and index all workflows with edge cases
/wiki flow-search <query>       → Search flows across all services
/wiki flow-list <service>       → List flows for a service
/wiki search <query>            → Search docs + notes + flows
/wiki get <service>             → Retrieve full doc
/wiki list                      → List all indexed services
/wiki stats                     → Knowledge base statistics

Self-Learning

Agents automatically add notes when they discover something new. Six note types:

Type	Trigger
`gotcha`	Unexpected behavior, edge case, known bug
`pattern`	Recurring pattern across 2+ services
`integration`	Undocumented service integration detail
`convention`	Code convention, naming pattern
`decision`	Design decision (lightweight ADR)
`tip`	Shortcut, useful command, workflow hack

Flows & Diagrams

Each flow is independently indexed with:

Mermaid sequence diagram (happy path + error paths + edge cases)
Keywords for discoverability
Linked services for cross-service navigation
Flow type: happy_path, error_path, edge_case, recovery, full

Diagrams render in the web UI via Mermaid.js. The UI also renders service documentation markdown (tables, code blocks, headings) via marked.js.

Architecture

src/
├── cli.ts              # CLI entry (8 commands)
├── mcp-server.ts       # MCP JSON-RPC server (12 tools)
├── ui-server.ts        # Web UI (marked.js + mermaid.js, flows tab)
├── lancedb/client.ts   # JSON file-backed storage (docs, notes, flows)
├── types.ts            # TypeScript types
└── index.ts            # Public API exports

docs/
├── getting-started.md
├── mcp-tools.md
├── self-learning.md
├── configuration.md
└── architecture.md

Storage: .codebase-wiki/rag_db/docs.json + notes.json + flows.json

License

MIT — Bruno Carreira