.omx Directory

Each project that uses OMX gets a .omx/ directory at the worktree root. This directory holds all session-scoped state: plans, logs, notes, wiki pages, research, and team coordination data. It is safe to commit the parts you want to persist (plans, wiki, specs) and gitignore the parts that are ephemeral (state, logs, sessions).

Directory layout

.omx/
├── state/                  # Runtime state files
│   ├── sessions/           # Per-session state subdirectories
│   │   └── {sessionId}/    # One directory per active session
│   └── team/               # Team pipeline coordination state
├── plans/                  # Planning documents written by $omc-plan / $ralplan
├── logs/                   # Hook pipeline and agent execution logs
├── notepad.md              # Persistent freeform notepad (readable by agents)
├── project-memory.json     # Structured project memory — directives and notes
├── research/               # Research documents produced by agent workflows
├── wiki/                   # LLM Wiki pages (see $wiki skill)
├── specs/                  # Specification documents for features or systems
└── sessions/               # Archived session summaries

Key entries

• state/ — Written and read by the OMX runtime. Contains team task queues, worker heartbeats, inbox files, and monitor snapshots. Mutate only via omx team api — direct writes break runtime invariants.
• state/sessions/{sessionId}/ — Per-session scratch state. Created at session start, useful for passing context between hook invocations within a session.
• plans/ — Output of $omc-plan and $ralplan. Read-only for agents executing a plan; written only by planning skills.
• logs/ — Raw logs from hook execution, OpenClaw command gateways, and team events. Append .jsonl files here for structured log aggregation.
• notepad.md — Freeform notes written by $note or manually. Agents running in the same worktree can read this file to pick up context left by earlier sessions.
• project-memory.json — Structured memory with directives and notes arrays. Persists cross-session decisions and constraints. Read by agents at startup when present.
• research/ — Documents produced by research-oriented workflows ($sciomc, $external-context, analyst agents).
• wiki/ — Markdown wiki pages managed by $wiki. Queryable and linkable across sessions.
• specs/ — Feature and system specifications. Typically authored manually or by $autopilot planning passes.

Recommended .gitignore additions

.omx/state/
.omx/logs/
.omx/sessions/

Keep .omx/plans/, .omx/wiki/, .omx/specs/, .omx/notepad.md, and .omx/project-memory.json in version control to share context across team members.

Related

• Configuration — config files that complement .omx/ state
• State tools — state_read, state_write, and related MCP tools
• Wiki — wiki MCP tools that read and write .omx/wiki/