Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/SamBleed/opencode-obsidian/llms.txt

Use this file to discover all available pages before exploring further.

Bunker OS is a folder of plain Markdown files that doubles as an OpenCode agent environment. There is no installation wizard, no cloud setup, and no account required — you clone the repository, open it in Obsidian, and point OpenCode at the same directory. The hooks, skills, and scripts are already wired together.
1
Clone the repository as your vault
2
The recommended way to use Bunker OS is to clone it directly as your Obsidian vault. This gives you the full repository structure, pre-configured hooks, all 13 skills, the test suite, and the n8n automation layer.
3
git clone https://github.com/SamBleed/opencode-obsidian.git
cd opencode-obsidian
4
Open the folder in Obsidian:
5
  • Launch Obsidian
  • Click Manage Vaults → Open folder as vault
  • Select the opencode-obsidian/ directory
    • 6
    Obsidian will load the vault with pre-configured community plugins (Calendar, Thino, Excalidraw, Banners) and CSS snippets already in place. The graph view, dashboard, and canvas layer are all ready to use immediately.
    7
    The wiki/ directory is gitignored — your personal notes, research, and knowledge pages stay local and never leave your machine.
    8
    Open OpenCode in the same directory
    9
    With the vault open in Obsidian, open OpenCode in the same opencode-obsidian/ folder. OpenCode will automatically discover the hooks/hooks.json file and register the four lifecycle hooks.
    10
    # From inside the cloned directory
opencode
    11
    OpenCode detects the following hooks automatically:
    12
    {
  "hooks": {
    "SessionStart": [ ... ],
    "PostCompact":  [ ... ],
    "PostToolUse":  [ ... ],
    "Stop":         [ ... ]
  }
}
    13
    There is nothing to configure. The agent runtime is active the moment OpenCode starts.
    14
    Verify hooks are active
    15
    At session start, OpenCode reads wiki/hot.md silently to restore recent context. You can confirm the SessionStart hook is working by checking the hooks file directly:
    16
    cat hooks/hooks.json
    17
    The SessionStart hook runs two actions every time a session opens:
    18
  • Command — prints the hot cache to the terminal if wiki/hot.md exists
  • Prompt — instructs OpenCode to silently read wiki/hot.md to restore context without announcing it
    • 19
    The Stop hook detects whether wiki/ was modified during the session and, if so, prompts OpenCode to update wiki/hot.md with a summary of changes — so the next session picks up exactly where this one left off.
    20
    Read wiki/hot.md at the start of any session where you want to resume previous work. It is a ~500-word summary of the most recent context: current focus, key recent facts, recent changes, and active threads.
    21
    Run your first commands
    22
    With OpenCode running inside opencode-obsidian/, you have access to all 13 bundled skills immediately. Start with any of these:
    23
    Autonomous research — 3-round web research loop that decomposes a topic into angles, searches and fetches sources, cross-references for gaps, and files everything into the wiki:
    24
    autoresearch zero-trust architecture
    25
    Wiki query — reads wiki/hot.md, then wiki/index.md, drills into relevant pages, and synthesizes an answer from what is actually in the wiki:
    26
    what do you know about n8n?
    27
    BM25 text retrieval — keyword search over wiki pages using the pure-Python BM25 index (no embeddings, no LLM needed for indexing):
    28
    python3 scripts/retrieve.py "BM25 retrieval"
    29
    Here is the full command reference for day-to-day use:
    30
    CommandActionautoresearch [topic]3-round autonomous web research. Decomposes, searches, filesretrieve [query]BM25 text search over wiki (no LLM needed for indexing)think [problem]10-principle decision frameworkingest [file]Ingest source: extract entities and concepts, create pagesingest all of theseBatch ingestion with parallel processingwhat do you know about XQuery the wiki: hot → index → pages → synthesizelint the wikiHealth check: orphans, dead links, gapssave thisSave current conversation as a wiki notecanvasOpen or create a visual canvascanvas add image [path]Add image to canvas
    31
    And the CLI scripts that work independently of OpenCode:
    32
    make test                              # 430 tests, 5 suites
./bin/bunker-check.sh                  # Local definition of done
./bin/wiki-integrity.sh                # Scan for orphans and broken links
./bin/evidence-index.sh                # Index evidence with SHA256
./bin/bunker.sh init                   # Vault health check
./bin/wiki-sync.sh --apply             # Sync + commit wiki
python3 scripts/retrieve.py build      # Rebuild BM25 index
python3 scripts/retrieve.py "query"    # BM25 text retrieval
    33
    Set up n8n automation (optional)
    34
    n8n is Bunker OS’s async nervous system — it handles webhooks, AI triage, GitHub issue creation, and multi-channel notifications. It runs entirely on Docker and communicates with OpenCode through an MCP bridge.
    35
    cd automation/n8n-lab
docker compose up -d
    36
    Once running, n8n is available at http://localhost:5678. Two workflows are active by default:
    37
  • Health Check — monitors system status every 5 minutes
  • Ultimate Alerter — multi-channel webhook alerts (Slack / Telegram / Discord)
    • 38
    To activate the full AOC v4 Enterprise pipeline (37 nodes, AI triage via OpenRouter, GitHub issue creation), configure the environment variables in automation/n8n-lab/.env with your OpenRouter API key, Discord webhook URL, and GitHub credentials, then import and activate bunker-aoc-v4-enterprise.json from the n8n UI.
    39
    # Verify n8n is running
docker ps --filter name=n8n

    ​
    Option 2: Use as a Reference from Another Project

    If you already have an OpenCode project and want to point it at Bunker OS as a shared knowledge base without making it your primary vault, add a reference block to your project’s AGENTS.md: 
    ## Wiki Knowledge Base
Path: /path/to/opencode-obsidian

When you need context:
1. Read wiki/hot.md first (recent context)
2. If not enough, read wiki/index.md
3. Only then read individual wiki pages
    This cross-project pattern means your coding projects, security reviews, and research sessions all draw from the same compounding knowledge base without any duplicate setup.

    ​
    Next Steps

    Once you have Bunker OS running, the highest-leverage first actions are:
    1. Drop a source into .raw/ and run ingest [filename] — the skill extracts entities, concepts, and relationships and creates 8–15 cross-referenced wiki pages automatically.
    2. Run autoresearch [topic] on any domain you work in regularly — it seeds the wiki with well-sourced, cross-referenced pages that all future sessions can build on.
    3. Run make test once to confirm your environment is healthy — all 430 tests should pass.

    Build docs developers (and LLMs) love

    Get started for freeTalk to us