.omx Directory

Each project that uses OMX has a .omx/ directory at the worktree root. Plans, logs, notes, wiki pages, research, and team coordination data are stored here. It is common practice to commit items meant for team sharing — such as plans, wiki pages, and specs — and to gitignore ephemeral items such as state, logs, and 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 created by $plan / $ralplan
├── logs/                   # Hook pipeline and agent execution logs
├── notepad.md              # Freeform notepad (readable by agents)
├── project-memory.json     # Structured project memory — directives and notes
├── research/               # Documents produced by research workflows
├── wiki/                   # LLM Wiki pages (managed by the $wiki skill)
├── specs/                  # Feature and system specification documents
└── sessions/               # Archived session summaries

Key entries

• state/ — Read and written by the OMX runtime. Contains team task queues, worker heartbeats, inbox files, and monitor snapshots. Use omx team api to mutate; do not write directly.
• state/sessions/{sessionId}/ — Per-session scratch state. Created at session start; used to pass context between hook invocations within the same session.
• plans/ — Output of $plan and $ralplan. Executing agents read these files; only planning skills write them.
• 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 read this file to pick up context from earlier sessions.
• project-memory.json — Structured memory with directives and notes arrays. Persists cross-session decisions and constraints.
• research/ — Documents produced by research-oriented workflows or analyst agents.
• wiki/ — Markdown wiki pages managed by $wiki. Queryable and linkable across sessions.
• specs/ — Feature and system specifications. Authored manually or generated by $autopilot planning passes.

Recommended .gitignore

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

Add .omx/plans/, .omx/wiki/, .omx/specs/, .omx/notepad.md, and .omx/project-memory.json to version control if you want to share context across team members.

Related

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