Chaos Notes

A minimal, file-based personal knowledge system designed for AI-assisted workflows.

Features

• One note per idea — notes evolve in place, no separate drafts
• Stable IDs — 21-character nanoid that never changes, even when renaming
• Minimal metadata — id, title, note kind, and optional status/tags
• Git-backed — optional automatic commit and push
• AI-native — works with any agent that can run shell commands
• Web UI — simple React app for human access

Works With

• OpenClaw
• Claude Code
• Codex
• Any AI assistant with shell access

Installation

Clone to your agent's skills directory:

# OpenClaw
git clone https://github.com/dooart/chaos.git ~/.openclaw/skills

# Claude Code
git clone https://github.com/dooart/chaos.git ~/.claude/skills

# Other agents - check your agent's docs for skills directory
git clone https://github.com/dooart/chaos.git /path/to/skills

❗ After cloning, run bun install from the repo root to install all dependencies (scripts + web). Then see SETUP.md to configure the web UI and optional git backup. The data directory (~/.chaos) is created automatically on first use.

Follows the AgentSkills format supported by most AI coding agents.

Structure

~/.chaos/               # Your data (default location)
├── notes/             # Your notes
└── assets/            # Images

/path/to/skills/chaos/  # Skill directory
├── SKILL.md           # Agent instructions
├── SETUP.md           # Setup guide
├── scripts/           # Automation scripts
├── web/               # React web UI + server
└── data/              # Symlink to ~/.chaos

Note Format

---
id: abc123def456ghi789012
title: My Note Title
kind: project
status: building
tags: [tag1, tag2]
---

# Content here

Markdown body with [[links]] to other notes by ID.

Source Note Convention (raw vs synthesis)

Chaos uses two note kinds for research workflows:

• kind: source — one external source, lightly processed at ingestion
• kind: synthesis — cross-source integration and conclusions

Current source format (recommended):

• ## Source
• ## Overview
• ## Main interesting ideas
• ## No-hype take

Optional sections: technical details, claims to verify, open questions.

Default behavior is light synthesis at ingestion, not full raw transcript dumps. Use targeted raw excerpts only when exact quoting is necessary.

Quick Start

After setup, ask your AI agent:

• "Create a note about project ideas"
• "Search my notes for anything about AI"
• "Update my todo note with a new item"

Or use the CLI directly:

# Create a note
bun scripts/chaos.ts new "My First Note"
bun scripts/chaos.ts new --kind=source "My Source Note"

# Search notes
bun scripts/chaos.ts search "keyword"

# Start the web UI
cd web && bun run server.ts

The CLI auto-syncs before each command (best effort):

• pulls the data repo (~/.chaos) if git-enabled
• pulls the chaos code repo itself before executing commands

License

MIT