# xos > xos is a methodology and CLI for developers who think and build in the same place. It co-locates **knowledge** (an Obsidian vault) and **code** (your git repos) in one directory tree, then indexes both into a single searchable knowledge graph that humans and AI agents navigate the same way. The CLI is a single Rust binary (xos). Linux requires glibc 2.39+ (Ubuntu 24.04+). Two trees, one workspace: `o/` is for thinking (knowledge, decisions, people, history), `x/` is for doing (code, infrastructure, deployments). The power is the bridge between them — a `CLAUDE.md` in `x/` cross-references notes in `o/`, and a project doc in `o/` points to its repo in `x/`. The workspace *is* the context, and agents are first-class citizens who receive the same context humans get. **⚠️ Work in progress.** xos is an early, opinionated tool developed in the open — not a polished product. It began as one developer's personal workflow, and adopting it currently means adopting that workflow. Notably, keeping the search index current is **manual**: if you don't re-run `xos index` after changing notes, you get stale/degraded results. Don't use xos unless you're comfortable running and updating it yourself. See [Status & Known Issues](https://www.iamxos.ai/docs/known-issues.md). This site is intentionally bot-friendly. This file is Markdown, meant to be read by LLMs and crawlers as well as people. ## Documentation Full documentation is not published on this site yet. It will live in the [icewaterlabs/xos](https://github.com/icewaterlabs/xos) GitHub repo once that repo is public. ## Optional - [Full documentation (single file)](https://www.iamxos.ai/llms-full.txt): All of the above concatenated for one-shot ingestion. - [Source on GitHub](https://github.com/icewaterlabs/xos): The `xos` CLI source, releases, and issues. - [Install script](https://github.com/icewaterlabs/xos/releases/latest/download/install.sh): The shell installer invoked by the one-line install command. # xos — Overview & Methodology > A methodology for developers who think and build in the same place. Co-locate knowledge and code in a single directory tree. > ⚠️ **Work in progress.** xos is early and opinionated — a personal tool developed in the open, not a finished product. Read [Status & Known Issues](https://www.iamxos.ai/docs/known-issues.md) before adopting it. ## The idea Most developers keep their thinking in one place (a notes app, a wiki, scattered docs) and their code in another (git repos on disk). The context that connects the two — *why* a decision was made, *who* asked for it, *which* code implements it — lives only in your head, and evaporates. xos collapses that gap. It puts **knowledge** and **code** in one workspace and indexes both into a single knowledge graph, so the link between a decision and its implementation is a first-class, queryable edge — not tribal memory. ## Two trees, one workspace ``` ~/ox/ ├── o/ # Knowledge — an Obsidian vault. Thinking. └── x/ # Code — your git repositories. Doing. ``` - **`o/` is for Thinking.** Knowledge, context, decisions, relationships, history. Obsidian's graph connects people to projects to timelines. This is your institutional memory. - **`x/` is for Doing.** Code, deployments, infrastructure. Each repo is self-contained with its own git history. This is where ideas become running software. The power is in the **bridge** between them. A `CLAUDE.md` in `x/` cross-references notes in `o/`. A project doc in `o/` points to its repo in `x/`. Context flows both directions. ## Core principles - **Craft over code.** Elegance through deliberate documentation and architecture. Every file, note, and commit reflects intentionality. - **Ruthless simplification.** Eliminate unnecessary complexity. Three similar lines are better than a premature abstraction. Don't design for hypothetical futures. - **Single source of truth.** Each fact exists in exactly one location. Don't duplicate. - **Progressive disclosure.** The workspace structure tells you where to look; the file tells you what you need; cross-references tell you where to go deeper. - **Agent-agnostic.** The methodology works with any AI tool — Claude, Gemini, Cursor, Copilot. The workspace *is* the context. Agents are first-class citizens who receive the same context humans get. ## Why agents love it Because the workspace is a plain directory tree of Markdown and code — navigable by construction — an AI agent traverses it exactly the way a human does. No special API, no wrapper. `.agents/AGENTS.md` provides universal instructions to any AI agent that opens the workspace. And `xos serve` exposes the indexed vault over the Model Context Protocol so agents can search it as a tool. When your agent searches for "auth migration," it finds the *decision* (a daily note in `o/`) **and** the *implementation* (the auth middleware in `x/`), ranked together. ## Next steps - [Installation](https://www.iamxos.ai/docs/installation.md) - [Workspace Structure](https://www.iamxos.ai/docs/workspace-structure.md) - [CLI Reference](https://www.iamxos.ai/docs/cli.md) # Installing xos > ⚠️ **Work in progress.** xos is an early, opinionated personal tool, not a polished product. Don't install it unless you're comfortable running and updating it yourself — including re-running `xos index` manually to keep results fresh. See [Status & Known Issues](https://www.iamxos.ai/docs/known-issues.md) first. xos ships a single Rust CLI binary (`xos`). One binary, every platform, zero dependencies. ## One-line install ```bash curl -fsSL https://github.com/icewaterlabs/xos/releases/latest/download/install.sh | sh ``` The installer detects your platform, fetches the latest release from [`icewaterlabs/xos`](https://github.com/icewaterlabs/xos), installs the binary to `~/.local/bin/xos`, and offers to add that directory to your `PATH`. > **Platform note:** Linux binaries require GLIBC 2.39+ (Ubuntu 24.04+, Fedora 40+). macOS and Windows are unaffected. ## Bootstrap a workspace ```bash xos init ``` `xos init` creates the directory tree, installs CLI dependencies, authenticates with GitHub, clones your organization's repos, and configures MCP servers — idempotent and safe to re-run. ``` $ xos init [1/9] Pre-flight checks... ok [2/9] Creating ~/ox directory tree... ok [3/9] Installing dependencies... ok [4/9] Configuring git... ok [5/9] Cloning org repos... 12 repos cloned [6/9] Syncing dotfiles... ok [7/9] Generating .xos/config.json... ok [8/9] Setting up MCP server... ok [9/9] Post-init verification... ok xos workspace ready at ~/ox Knowledge: o/o/ (0 notes) Code: x/code/ (12 repos) Agents: .agents/ configured ``` ### Useful `xos init` flags | Flag | Purpose | |------|---------| | `--path` | Workspace path (default: `~/ox`) | | `--org` | GitHub organization to clone | | `--dotfiles` | Dotfiles repo, e.g. `yourname/xos-dotfiles` | | `--branch` | Dotfiles repo branch (default `main`) | | `--parallel` | Max parallel git clones (default 4) | | `--skip-clone` | Skip repository cloning | | `--skip-deps` | Skip CLI dependency installation | | `--skip-dotfiles` | Skip dotfiles sync | | `--skip-mcp` | Skip MCP server configuration | ## Verify ```bash xos version xos status # workspace health and status ``` ## Next steps - [CLI Reference](https://www.iamxos.ai/docs/cli.md) — every command - [Knowledge Graph & RAG](https://www.iamxos.ai/docs/knowledge-graph-rag.md) — run `xos index` then `xos search` - [MCP Server](https://www.iamxos.ai/docs/mcp-server.md) — connect your AI agent # xos CLI Reference > **Scope:** This reference covers the xos CLI (Rust). `xos` is a CLI tool for bootstrapping and managing xos workspaces. One binary, every platform, zero dependencies. ``` Usage: xos [command] ``` ## Commands | Command | Description | |---------|-------------| | `xos init` | Initialize a new xos workspace on this machine | | `xos clone [org]` | Clone or update all repos for a GitHub organization | | `xos index` | Index the knowledge base and code for search and graph queries | | `xos search ` | Search using hybrid text + vector search | | `xos serve` | Start the MCP server for AI agent integration | | `xos status` | Show workspace health and status | | `xos kb` | Manage knowledge bases (create, info, list, switch) | | `xos workspace` | Start the xos workspace web UI | | `xos version` | Print the xos version | | `xos completion` | Generate a shell autocompletion script | Run `xos [command] --help` for details on any command. ## xos init Creates the directory structure, installs CLI dependencies, authenticates with GitHub, clones organization repos, and configures MCP servers. See [Installation](https://www.iamxos.ai/docs/installation.md) for the full flag list. ## xos clone ```bash xos clone [org] [--parallel N] ``` Clones all non-archived repos for a GitHub organization into `x/code/remote/github//`. Existing repos are skipped (not force-updated). ## xos index ```bash xos index [flags] ``` Parses all Markdown notes and code repositories, builds a knowledge graph, generates embeddings, and creates full-text search indexes. By default indexes **both** the knowledge base (`o/o/`) and code repos (`x/code/`). Incremental by default via SHA-256 content hashing. | Flag | Purpose | |------|---------| | `--kb-only` | Only index the knowledge base | | `--code-only` | Only index code repos | | `--full` | Force a full re-index (ignore the content-hash cache) | | `--no-embed` | Skip embedding generation (no Ollama needed) | | `--model` | Embedding model (default `nomic-embed-text`) | | `--ollama-url` | Ollama API URL (default `http://localhost:11434`) | ## xos search ```bash xos search [-n LIMIT] [--text-only] ``` Combines BM25 full-text search with semantic vector similarity for ranked results across knowledge **and** code. | Flag | Purpose | |------|---------| | `-n, --limit` | Maximum results (default 20) | | `--text-only` | BM25 text search only (no embeddings) | ## xos serve ```bash xos serve [flags] ``` Starts a Model Context Protocol (MCP) server on stdio, exposing knowledge-base search and graph tools to Claude Code and other MCP clients. Add to `.mcp.json` to auto-connect: ```json { "xos": { "type": "stdio", "command": "xos", "args": ["serve"] } } ``` | Flag | Purpose | |------|---------| | `--no-embed` | Disable embeddings; use BM25 + graph only (no Ollama required) | See [MCP Server](https://www.iamxos.ai/docs/mcp-server.md). ## xos kb Manage one or more knowledge bases (directories of Markdown using the who/what/when/where convention). Subcommands: `create`, `info`, `list`, `switch`. Use any editor — Obsidian, VS Code, or the xos web UI. ## xos status Shows workspace health and status — note counts, indexed repos, and configuration state. # Workspace Structure The xos workspace follows the "two trees, one workspace" pattern: `o/` for knowledge, `x/` for code. ``` ~/ox/ # Workspace root (NOT a git repo) ├── .agents/ # Universal agent context │ ├── workspace-structure.md # This document │ ├── philosophy.md # Team values & principles │ ├── SOUL.md # Identity & behavioral core │ ├── IDENTITY.md # Agent behavioral guidelines │ ├── AGENTS.md # Agent workspace rules │ └── shared/ # Operational state │ ├── deployments.md # Live deployment map │ └── infrastructure.yaml # Single source of truth for infra │ ├── o/ # Obsidian vault (knowledge layer) │ ├── .obsidian/ # Vault configuration │ └── o/ # Vault content root │ ├── who/ # People — every person gets a linked note │ ├── what/ # Projects, orgs, tools, topics │ │ ├── orgs/ │ │ │ ├── COM/ # Commercial organizations │ │ │ ├── EDU/ # Educational institutions │ │ │ └── FAM/ # Family organizations │ │ ├── bots/ # AI agent notes & shared memory │ │ │ └── memory/ # Cross-device synced memory │ │ └── [topics]/ # Skills, tools, career, essays, etc. │ ├── when/ # Temporal — daily notes, cycles, events │ │ ├── days/ # Daily notes │ │ ├── weeks/ months/ quarters/ years/ │ │ ├── cycles/ # Sprint/project cycles │ │ └── events/ # Calendar events │ └── where/ # Geolocation only (physical places) │ └── x/ # Code layer └── code/ └── remote/ └── github/ └── / # One directory per GitHub org └── / # Each repo keeps its own .git history ``` ## Conventions - **Two trees:** `o/` is for thinking (knowledge), `x/` is for doing (code). - **Repository paths mirror the remote:** `x/code/remote/{host}/{org}/{repo}/`. All code repos are checked out under `x/code/`. - **Wikilinks use absolute vault-root paths:** `[[o/who/John Doe]]`, `[[o/what/orgs/COM/iwl/infrastructure]]`. - **`o/where/` is reserved for geolocation only** — infrastructure notes live under `o/what/orgs/...`. - **Every repo includes a `CLAUDE.md`** for agent onboarding, cross-referencing the relevant notes in `o/`. - **The who/what/when/where convention** organizes the vault: people, things, time, and place. See also: [Methodology](https://www.iamxos.ai/docs/methodology.md) · [Code Indexing](https://www.iamxos.ai/docs/code-indexing.md) # Knowledge Graph & RAG xos indexes your vault into a searchable knowledge graph with hybrid retrieval — BM25 full-text search combined with vector similarity — so both exact terms and semantic meaning rank together. ## Hybrid search - **BM25 full-text** via tantivy for precise keyword matching. - **Vector similarity** via Ollama embeddings (opt-in; default model: `nomic-embed-text`) for semantic recall. - Results from both are merged and ranked. ``` $ xos index Indexing vault at ~/ox/o/o/... Parsed 847 notes, 2,341 links, 892 tags Generated 847 embeddings (nomic-embed-text) Graph: 1,739 nodes, 3,233 edges Index time: 12.4s (incremental: 0.8s) $ xos search "auth migration decision" 0.94 o/when/days/2026.March.16.Monday.md "discussed auth migration with Alice..." 0.87 o/what/orgs/COM/iwl/maxre/auth-decisions.md "JWT refresh token rotation strategy..." 0.81 x/code/.../crm-api/CLAUDE.md "Auth middleware uses Supabase JWT..." Results: 3 (0.04s) ``` ## The graph A CozoDB embedded graph stores **nodes** (notes, tags) and **edges** (`LINKS_TO`, `HAS_TAG`). Wikilinks between notes and tags become traversable relationships, so you can ask not just "what matches" but "what's related." ## Storage stack - **Default stack:** CozoDB embedded graph + tantivy BM25 (zero cloud dependencies, runs fully local). - **Embeddings:** Ollama opt-in (run with a local Ollama instance for semantic search). ## Incremental & safe - **Incremental indexing** with SHA-256 change detection — only re-index what changed (`xos index` re-runs in well under a second on an unchanged vault; use `--full` to force). - **Read-only search mode** — no file-lock conflicts with your editor. - **No embeddings needed?** `xos index --no-embed` skips Ollama and runs text-only. ## Next steps - [Code Indexing](https://www.iamxos.ai/docs/code-indexing.md) — index repos alongside notes - [MCP Server](https://www.iamxos.ai/docs/mcp-server.md) — expose search to AI agents - [CLI Reference](https://www.iamxos.ai/docs/cli.md#xos-index) # Code Indexing xos indexes your **code** alongside your **notes** — both land in the same knowledge graph, so a single search returns decisions *and* the implementations that satisfy them. ## Your notes AND your repos, in one graph `xos index` walks the repos in `x/code/` together with the vault notes in `o/o/`. File trees, symbols, git metadata, and dependencies all become nodes and edges in the same graph as your knowledge. The result: a note about an "auth migration" links to the actual auth code. When your AI agent searches, it finds the *decision* in `o/` **and** the *implementation* in `x/`, ranked together. ``` o/when/days/2026.March.16.md ──LINKS_TO──▶ o/what/orgs/.../auth-decisions.md │ cross-reference ▼ x/code/.../crm-api/CLAUDE.md ──DESCRIBES──▶ x/code/.../crm-api/auth/middleware.ts ``` ## Why it matters Most tools index either your knowledge **or** your code. xos co-locates them, so the bridge between *why* and *how* is a queryable edge rather than something you reconstruct from memory. Think of it like a code-graph tool (e.g. GitNexus) — but co-located with your knowledge base instead of standing apart from it. ## Selective indexing ```bash xos index # both knowledge and code (default) xos index --kb-only # notes only xos index --code-only # repos only ``` Indexing is incremental (SHA-256 change detection), so re-runs are fast. See the [CLI Reference](https://www.iamxos.ai/docs/cli.md#xos-index) for all flags. ## Next steps - [Knowledge Graph & RAG](https://www.iamxos.ai/docs/knowledge-graph-rag.md) - [MCP Server](https://www.iamxos.ai/docs/mcp-server.md) — let agents query the combined graph # MCP Server `xos serve` turns your workspace into a tool for AI agents. It starts a Model Context Protocol (MCP) server on stdio, exposing knowledge-base search and graph tools to Claude Code, Cursor, Windsurf, and any MCP-compatible agent. The xos CLI includes an MCP server that exposes 6 tools. ## Connect Add xos to your `.mcp.json` to auto-connect: ```json { "mcpServers": { "xos": { "type": "stdio", "command": "xos", "args": ["serve"] } } } ``` ## Tools exposed | Tool | Purpose | |------|---------| | `search_vault` | Hybrid BM25 + vector search across notes and repo docs | | `get_note` | Read a note's full text by path | | `find_related` | Graph neighbors + semantic similarity from a note | | `get_backlinks` | Inbound wikilinks to a note | | `vault_stats` | Index statistics (note count, edge count, tags) | | `find_path` | Shortest graph path between two notes (requires optional Neo4j backend) | ## In practice ``` # Agent query (via Claude Code): > Search vault for "deployment checklist" search_vault("deployment checklist") -> 3 results in 0.04s -> o/what/orgs/COM/iwl/deploy-checklist.md (0.96) -> o/when/days/2026.March.20.Thursday.md (0.84) -> x/code/.../infra/docs/DEPLOY.md (0.79) ``` ## Agent-navigable by construction The agent traverses the same tree humans do — no special API, no wrapper. Two things make the workspace agent-ready out of the box: - **`.agents/AGENTS.md`** provides universal instructions for any AI agent that opens the workspace. - **The MCP server** gives agents fast, ranked retrieval over the indexed graph. Agents are first-class citizens in xos: they receive the same context humans get. ## Next steps - [CLI Reference](https://www.iamxos.ai/docs/cli.md#xos-serve) - [Knowledge Graph & RAG](https://www.iamxos.ai/docs/knowledge-graph-rag.md) # The xos CLI xos ships a single Rust CLI (`xos`). The Go CLI has been retired as of ADR-0015. There is now one binary, one implementation. - CozoDB embedded graph engine - tantivy BM25 full-text search - Ollama opt-in for vector embeddings - ratatui TUI (`xos tui`) - MCP server (6 tools: `search_vault`, `get_note`, `find_related`, `get_backlinks`, `vault_stats`, `find_path`) - `xos init` / `xos clone` for workspace bootstrapping - Takes `--vault /path` or `OX_VAULT` env variable - **Linux requires GLIBC 2.39+** (Ubuntu 24.04+, Fedora 40+). macOS and Windows are unaffected. ## Installation ```bash curl -fsSL https://github.com/icewaterlabs/xos/releases/latest/download/install.sh | sh ``` The installer detects your platform and installs the binary to `~/.local/bin/xos`. # Status & Known Issues > ⚠️ **xos is a work in progress.** It is an early, opinionated tool developed in the open — not a polished product. It began as one developer's personal workflow, and adopting it currently means adopting that workflow. **Don't use xos unless you're comfortable running and updating it yourself.** Expect rough edges. ## The big caveat: indexing is manual Keeping the search index current is **a manual step**. `xos search` and the MCP tools only reflect the vault/code state as of the last `xos index` run. If you add or edit notes and don't re-index, you silently get **stale or degraded results** — no error, just missing or outdated hits. ```bash xos index # re-run this after changing notes/code, or results drift ``` If results look wrong or incomplete, re-index first. ## Known issues These are tracked on GitHub. See the live list: **[github.com/icewaterlabs/xos · label:known-issue](https://github.com/icewaterlabs/xos/issues?q=is%3Aissue+is%3Aopen+label%3Aknown-issue)** | # | Issue | Status | |---|-------|--------| | [#70](https://github.com/icewaterlabs/xos/issues/70) | `xos index` is manual — a stale index silently degrades search/MCP results | Open | | [#71](https://github.com/icewaterlabs/xos/issues/71) | `xos index` can appear to hang near the tail on large vaults | Open | | [#72](https://github.com/icewaterlabs/xos/issues/72) | `xos tui` (Go CLI): removed. xos ships a ratatui TUI (Phase 6). | Closed — resolved in xos | | [#73](https://github.com/icewaterlabs/xos/issues/73) | Workspace structure is rigid / not pluggable (`~/ox` + `o/o/who-what-when-where` + Obsidian) | Open | | [#74](https://github.com/icewaterlabs/xos/issues/74) | Embeddings require a running Ollama; silent fallback to text-only (use `xos serve --no-embed` to opt out explicitly) | Open | | [#75](https://github.com/icewaterlabs/xos/issues/75) | bbolt CVE (CVE-2026-33817, indirect via Bleve) | Closed — resolved in v0.3.0 (bbolt v1.4.0) | ## xos dependency advisories Two upstream RUSTSEC advisories affect xos's graph engine dependency chain (cozo → swapvec): - **lz4_flex** (HIGH): memory-safety issue in older lz4 flex bindings - **lru** (LOW): algorithmic complexity issue in LRU cache Both are upstream-blocked — fixes depend on swapvec and tantivy releasing updated versions. Both are documented in CI with ignore justifications. Monitor when swapvec and tantivy release updates. Found something not listed? Open an issue: . ## What's solid For balance — the parts that are genuinely good today: - **Hybrid search engine** — BM25 + vector similarity over a SQLite graph is fast and the ranking is useful (once the index is current). - **MCP server** — all six tools (`search_vault`, `get_note`, `find_related`, `get_backlinks`, `vault_stats`, `find_path`) work well against real agent sessions. - **Co-located knowledge + code** — the core idea (one graph over notes *and* repos) holds up. See [Methodology](https://www.iamxos.ai/docs/methodology.md) for the philosophy and [CLI Reference](https://www.iamxos.ai/docs/cli.md) for commands.