# OX — 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.** OX is early and opinionated — a personal tool developed in the open, not a finished product. Read [Status & Known Issues](https://iamox.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.

OX 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 `ox 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://iamox.ai/docs/installation.md)
- [Workspace Structure](https://iamox.ai/docs/workspace-structure.md)
- [CLI Reference](https://iamox.ai/docs/cli.md)