Crux

Markdown-native, lazy-loading, multi-agent workspace. Every rule, every identity, every protocol lives in a plain text file. No runtime required to read or understand what the system is doing.

Installation

Quick start

curl -fsSL https://raw.githubusercontent.com/dotlabshq/crux/main/scripts/install.sh | bash

Windows PowerShell

irm https://raw.githubusercontent.com/dotlabshq/crux/main/scripts/install.ps1 | iex

With options

curl -fsSL https://raw.githubusercontent.com/dotlabshq/crux/main/scripts/install.sh | bash -s -- \
  --tool opencode

Option	Description	Default
`--agents`	Comma-separated agent IDs to install	all available
`--tool`	Target AI tool: `opencode` · `claude-code` · `cursor` · `codex` · `all`	auto-detect
`--project`	Project name used during workspace initialisation	—
`--force`	Overwrite existing framework-home files	false
`--dry-run`	Preview without writing files	false

After install

Start your AI tool in the project directory. The install script places reusable Crux framework files under the user's framework home, normally $HOME/.crux. The project-local .crux/ directory is reserved for project knowledge, decisions, generated references, and live workspace state. The project root AGENTS.md is the bootstrap entrypoint and points agents to the Crux coordinator skill. Framework management scripts live under $HOME/.crux/scripts/; the installer does not keep Crux scripts in the project folder.

@kubernetes-admin   cluster health, namespaces, tenant provisioning
@postgresql-admin   schema inspection, roles, backups, tenant provisioning

Keeping agents in sync

After editing any framework-home agents/ or skills/ file, re-run:

$HOME/.crux/scripts/convert.sh

On Windows PowerShell:

$HOME\.crux\scripts\convert.ps1

This syncs agent and skill definitions to tool-specific locations (.opencode/agent/, .claude/agents/, .cursor/rules/, Codex wrapper skills under $CODEX_HOME/skills/crux/<project>/agents/).

Updating from the Crux repo

To pull the latest agent, skill, and framework files from the upstream Crux repo:

$HOME/.crux/scripts/update.sh

On Windows PowerShell:

$HOME\.crux\scripts\update.ps1

This overwrites framework-home agents/, skills/, templates, and other framework files with the latest versions, then re-runs convert.sh. Local customisations to framework-home files will be lost.

# Update specific agents only
$HOME/.crux/scripts/update.sh --agents kubernetes-admin,postgresql-admin

# Preview without writing
$HOME/.crux/scripts/update.sh --dry-run

Directory Structure

Crux separates reusable framework definitions from project-local knowledge and runtime state.

$HOME/.crux/               framework home, read mostly
├── agents/                reusable agent identities and onboarding protocols
├── scripts/               framework management scripts
├── skills/                reusable SKILL.md task protocols
│   └── crux-coordinator/  canonical Crux boot, routing, and path protocol
├── templates/             reusable starter templates
├── workflows/             reusable workflow definitions
├── bus/                   reusable bus protocol docs
├── docs/                  framework-level references
└── COORDINATOR.md         legacy coordinator document

{project}/AGENTS.md        project bootstrap; read crux-coordinator first

{project}/.crux/           project knowledge and live state
├── CONSTITUTION.md        generated project rules
├── SOUL.md                generated project identity defaults
├── docs/                  compiled project knowledge, generated from agent assets
├── summaries/             token-efficient summaries of docs/
├── decisions/             project decisions and cross-agent standards
├── workflows/             project-specific generated workflows, when needed
├── bus/                   project-local bus/events, when enabled
└── workspace/             live state, normally gitignored
    ├── MANIFEST.md        Live system state — agent status, pending amendments.
    ├── TODO.md            Coordinator canonical task state.
    ├── inbox.md           Human approvals, handoffs, and pending operator decisions.
    ├── MEMORY.md          Coordinator persistent memory.
    ├── current            Symlink → sessions/{active-ulid}/
    ├── sessions/          Coordinator sessions.
    │   └── {ulid}/
    │       ├── scratch.md
    │       ├── context-cache.md
    │       └── summary.md
    │
    └── {role-id}/         Per-agent workspace.
        ├── MEMORY.md      Agent persistent memory — facts, decisions, conventions.
        ├── TODO.md        Agent canonical task state — source of truth for task continuity.
        ├── NOTES.md       Operational state — issues, pending tasks, discoveries.
        ├── output/        Files generated by this agent. Persistent.
        ├── current        Symlink → sessions/{active-ulid}/
        └── sessions/
            └── {ulid}/
                ├── scratch.md
                ├── context-cache.md
                └── summary.md

The project .crux/docs/, .crux/summaries/, and .crux/decisions/ act as Crux's compiled project knowledge layer. This follows the LLM Wiki pattern: sources and interactions are distilled into durable markdown that future agents can read directly, without copying global agent or skill definitions into the project.

Static vs Dynamic

Path	Type	Git	Created by
`.crux/CONSTITUTION.md`	generated static	after onboarding	coordinator during workspace initialisation
`.crux/SOUL.md`	generated static	after onboarding	coordinator during workspace initialisation
`$HOME/.crux/COORDINATOR.md`	framework static	external	framework install/update
`AGENTS.md`	project bootstrap	✓	install script, preserving existing project guidance
`../README.md`	static	✓	manual — project root, human docs
`$HOME/.crux/templates/*`	framework static	external	framework install/update
`$HOME/.crux/agents/{role}/AGENT.md`	framework static	external	manual from template
`$HOME/.crux/agents/{role}/onboarding.md`	framework static	external	manual from template
`$HOME/.crux/skills/{name}/SKILL.md`	framework static	external	manual from template
`$HOME/.crux/workflows/{name}.md`	framework static	external	manual from template
`.crux/decisions/{id}.md`	generated static	after onboarding	agent proposes + user approves, OR coordinator generates during onboarding
`.crux/docs/{topic}.md`	generated static	after onboarding	onboarding, lazy-loading, or skills from owning agent assets
`.crux/summaries/{topic}.md`	generated static	after onboarding	doc-summariser skill
`.crux/workspace/`	dynamic	✗	coordinator during workspace initialisation
`.crux/workspace/MANIFEST.md`	dynamic	✗	coordinator during onboarding / workspace initialisation
`.crux/workspace/TODO.md`	dynamic	✗	coordinator during onboarding / workspace initialisation
`.crux/workspace/MEMORY.md`	dynamic	✗	coordinator during onboarding / workspace initialisation
`.crux/workspace/inbox.md`	dynamic	✗	coordinator during onboarding / workspace initialisation
`.crux/workspace/sessions/{ulid}/`	dynamic	✗	coordinator at session start
`.crux/workspace/{role}/MEMORY.md`	dynamic	✗	onboarding
`.crux/workspace/{role}/TODO.md`	dynamic	✗	onboarding
`.crux/workspace/{role}/NOTES.md`	dynamic	✗	onboarding
`.crux/workspace/{role}/sessions/{ulid}/`	dynamic	✗	coordinator at session start

Context Loading Order

Every agent loads files in this order:

1. .crux/CONSTITUTION.md                    ~1000 tokens   always
2. .crux/SOUL.md                            ~500  tokens   always
3. {framework-home}/agents/{role}/AGENT.md  ~800  tokens   always
4. .crux/workspace/{role}/MEMORY.md         ~400  tokens   always
5. .crux/workspace/{role}/TODO.md           ~300  tokens   always
─────────────────────────────────────────────────────────────────
Base cost:                                  ~3000 tokens

6. .crux/workspace/{role}/NOTES.md          session start  supporting context for open tasks
7. .crux/summaries/{doc}.md                 on demand      overview sufficient
8. .crux/docs/{doc}.md                      on demand      generate if missing, then load
9. .crux/decisions/{id}.md                  on demand      when decision is referenced
10. {framework-home}/skills/{name}/SKILL.md on trigger     unloaded after use

Coordinator additionally loads on workflow trigger:

{framework-home}/workflows/{name}.md or .crux/workflows/{name}.md
                                             on trigger     unloaded after workflow completes

Hard limit: 8000 tokens before execution begins.

Three Layers

$HOME/.crux/        framework   reusable protocols     read mostly, externally updated
.crux/docs/         compiled    project knowledge      may be committed
.crux/summaries/    compiled    compact project docs   may be committed
.crux/decisions/    compiled    approved decisions     may be committed
.crux/workspace/    dynamic     live state             gitignored
.crux/workspace/sessions/ ephemeral coordinator work   gitignored
.crux/workspace/{role}/sessions/ ephemeral agent work  gitignored

Onboarding Flow

When an agent starts and .crux/workspace/MANIFEST.md shows status: pending-onboard:

1. Run environment discovery (silent checks)
2. Ask user only what could not be discovered
3. Generate missing `.crux/docs/` references from framework-home agent assets if needed
4. Run required skills → generate project docs, decisions, or notes-root content
5. Write facts to `.crux/workspace/{role}/MEMORY.md`
6. Create `.crux/workspace/{role}/NOTES.md` from template
7. Update `.crux/workspace/MANIFEST.md` status → onboarded
8. Broadcast agent.onboarded event

Workflow Flow

When the coordinator detects a workflow trigger phrase:

1. Load `{framework-home}/workflows/{name}.md` or project `.crux/workflows/{name}.md`
2. Collect inputs from user (one at a time, validate before proceeding)
3. For each step:
     a. Check owning agent is onboarded (`.crux/workspace/MANIFEST.md` status == onboarded)
        not onboarded + required: yes  → stop
        not onboarded + required: no   → skip, continue
     b. Check coordinator and agent `TODO.md` for an existing open task matching this step
     c. Delegate to agent via @mention, passing inputs
     d. Treat completion as `TODO.md` status = `done`, not merely "agent replied"
     e. Record step result in `.crux/workspace/sessions/{id}/scratch.md`
4. Coordinator runs Finalise: update `.crux/workspace/MANIFEST.md`, broadcast event, notify user
5. On required step failure → run rollback as defined in workflow file

Task State Model

Crux separates task state from notes:

.crux/workspace/TODO.md = coordinator source of truth for task continuity
.crux/workspace/{role}/TODO.md = agent source of truth for task continuity
.crux/workspace/{role}/NOTES.md = supporting context, discoveries, and workarounds
.crux/workspace/inbox.md = human approvals and operator decisions
.crux/workspace/MANIFEST.md = system summary

Coordinator write scope:

may write: .crux/workspace/MANIFEST.md, .crux/workspace/TODO.md, .crux/workspace/inbox.md, .crux/workspace/MEMORY.md, coordinator sessions, bus files, and task stubs/status in .crux/workspace/{role}/TODO.md
must not write: .crux/workspace/{role}/MEMORY.md, .crux/workspace/{role}/NOTES.md, .crux/workspace/{role}/output/**, .crux/docs/**, decisions/**, or domain-owned project files
if work requires a forbidden write, coordinator delegates instead of completing it directly

Agents and coordinator should:

read TODO.md before starting new work
reuse a matching open task instead of silently starting over
update task status before and after meaningful execution
use done, waiting, blocked, or canceled explicitly at session end

Amendment Flow

1. Agent writes AMD-{id} to `.crux/workspace/MANIFEST.md` → Pending Amendments
2. Agent pauses and notifies user
3. User approves → .crux/CONSTITUTION.md updated, version incremented
4. User rejects → agent continues under current rule

@Mention Modes

Mode	Behaviour
`primary`	Direct handoff in same context (Tab switcher)
`subagent`	Invoked via @mention or by primary agent

.gitignore

.crux/workspace/

Everything under .crux/workspace/ is gitignored. Project .crux/docs/, .crux/summaries/, and .crux/decisions/ are compiled project knowledge and may be committed when useful.

Adding Agents, Skills, and Workflows

Agent:    copy templates/AGENT.template.md      → agents/{role}/AGENT.md
          copy templates/onboarding.template.md → agents/{role}/onboarding.md
          add agent-local assets under          → agents/{role}/assets/   (if the agent generates `.crux/docs/*`)
          run: $HOME/.crux/scripts/convert.sh

Skill:    copy templates/SKILL.template.md      → skills/{name}/SKILL.md
          run: $HOME/.crux/scripts/convert.sh

Workflow: copy templates/WORKFLOW.template.md   → workflows/{name}.md
          update `.crux/workspace/MANIFEST.md` Workflows table when enabled in a project

Three-Layer Model

Concept	Where	Scope	Git
Skill	`$HOME/.crux/skills/{name}/SKILL.md`	One agent, one task	external
Workflow	`$HOME/.crux/workflows/{name}.md` or `.crux/workflows/{name}.md`	Coordinator + multiple agents	external or project
Decision	`.crux/decisions/{id}.md`	Human-approved, permanent project record	✓
Doc	`.crux/docs/{topic}.md`	Generated project knowledge, replaceable	✓
Memory	`.crux/workspace/{role}/MEMORY.md`	Agent runtime state	✗

Source vs Framework Home vs Project Runtime

Crux keeps a strict separation between framework source, framework home, and project runtime:

Source repo layout is for framework development only.
Framework home ($HOME/.crux) stores reusable agent, skill, template, and workflow definitions.
Project .crux stores generated project knowledge and live workspace state.
Global framework files are treated as read-only during project operation.
Generated project docs, summaries, workspace, and user outputs must never be written back into framework home.

See docs/source-layout.md for the explicit mapping table and generation rules.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Crux

Installation

Quick start

Windows PowerShell

With options

After install

Keeping agents in sync

Updating from the Crux repo

Directory Structure

Static vs Dynamic

Context Loading Order

Three Layers

Onboarding Flow

Workflow Flow

Task State Model

Amendment Flow

@Mention Modes

.gitignore

Adding Agents, Skills, and Workflows

Three-Layer Model

Source vs Framework Home vs Project Runtime

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
agents		agents
bus		bus
docs		docs
scripts		scripts
skills		skills
templates		templates
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
COORDINATOR.md		COORDINATOR.md
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

Crux

Installation

Quick start

Windows PowerShell

With options

After install

Keeping agents in sync

Updating from the Crux repo

Directory Structure

Static vs Dynamic

Context Loading Order

Three Layers

Onboarding Flow

Workflow Flow

Task State Model

Amendment Flow

@Mention Modes

.gitignore

Adding Agents, Skills, and Workflows

Three-Layer Model

Source vs Framework Home vs Project Runtime

About

Topics

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages