ClawMD

A POSIX-like standard for agentic external context, built on Git, JSON, Markdown, and frontmatter.

What is it?

ClawMD defines a convention for structuring Git repositories so that AI agents (and humans) can reliably discover, read, and write temporal and static context without exploding their context windows.

It's two things:

1. STANDARD.md — the specification. Implementation-agnostic. Any tool, script, or service that follows these conventions is "clawmd-compliant".
2. clawmd — a reference CLI client written in Go that talks to Gitea instances.

Core idea

Agents need context, but context windows are finite. ClawMD gives you:

• Workspaces — markdown files loaded into agent context (identity, rules, background)
• Timelines — append-only dated markdown entries with delta reads
• Boards — structured key-value state (JSON/YAML)
• Threads — Git issues used as conversation channels
• Signals — webhook events routed through automation (n8n, etc.)

The key invariant: clawmd timeline read with no flags returns only what the agent hasn't seen. Full reads require explicit opt-in.

Quick start

Any repo with a content.md that has ## YYYY-MM-DD headings is already clawmd-compliant. Zero configuration needed.

With the CLI

go install github.com/mythosxyz/clawmd@latest

# Configure your Gitea instance
clawmd config set giteaUrl http://your-gitea:3000
clawmd config set token YOUR_TOKEN

# Read workspace files from a repo
clawmd workspace read Team/myproject

# Read only new timeline entries since last read
clawmd timeline read Team/myproject

# Append a timeline entry
clawmd timeline append Team/myproject --entry "Deployed v1.0 to production"

# Get a board value
clawmd board get Team/myproject status.json phones.rob-iphone.status

# Set a board value
clawmd board set Team/myproject status.json phones.rob-iphone.status online

# Read thread (issue) comments since last read
clawmd thread read Team/myproject 42

With a clawmd.yaml

Create a clawmd.yaml in your repo root to declare the full structure:

version: 1

workspace:
  - path: SOUL.md
    role: identity
  - path: CONTEXT.md
    role: context
  - path: RULES.md
    role: rules

timelines:
  - path: content.md
    format: markdown-dates

boards:
  - path: status.json
    format: json

threads:
  labels: []
  at-home-label: AT HOME

Why?

Multi-agent systems need shared context. The options before ClawMD were:

• Stuff everything into the system prompt (context window explosion)
• Poll everything every time (wasteful, slow)
• Build custom integrations per agent (fragile, not portable)

ClawMD says: use Git as the backing store, markdown as the format, and track what you've already read. It's boring technology used deliberately.

The standard

The full specification lives in STANDARD.md. It covers:

• Workspace loading and multi-agent filtering
• Timeline format (markdown-dates, reverse chronological)
• Temporal read protocol (delta by default, full on demand)
• Board read/write with optimistic concurrency
• Thread temporal reads via issue comments
• Signal payloads and webhook integration patterns
• Cross-repo references
• State file locations and cold-start behavior

Composability

ClawMD is not just a CLI. Any system can produce clawmd-compliant content:

[Monitoring Service] → n8n workflow → clawmd board (status.json)
[CI Pipeline]        → n8n workflow → clawmd timeline (content.md)
[Game Server Logs]   → script       → clawmd timeline (content.md)

If it writes markdown with date headers or JSON with key-value pairs to a Git repo, it's clawmd-compliant.

License

Apache License 2.0 — see LICENSE.