creworg

A file-system based agent swarm. Directory structure maps to organizational hierarchy; agents communicate exclusively through file reads and writes.

✨ Features

• 🌳 Hierarchical Organization - Agents arranged in parent-child trees, mirroring real org structures
• 📁 File-Based Communication - All agent state lives in files, no databases required
• 🔄 Real-Time Coordination - Automatic task delegation and result aggregation
• 🎯 Targeted Watching - Efficient file watching, no EMFILE errors
• 🧠 Persistent Memory - Each agent maintains its own memory across sessions
• 🔧 Extensible Tools - Custom tools and hooks for specialized workflows
• 🖥️ Live TUI - Beautiful terminal interface showing agent activity in real-time

🚀 Quick Start

Installation

npm install -g creworg

Setup

1. Create a .env file with your Anthropic API key:

echo "ANTHROPIC_API_KEY=sk-ant-..." > .env

2. Create your first agent:

mkdir -p @ceo/.agent

3. Define the agent's identity in @ceo/.agent/IDENTITY.md:

# Identity

name: ceo
emoji: 👔
role: Chief Executive Officer

4. Define the agent's personality in @ceo/.agent/SOUL.md:

# Soul

You are a strategic leader who delegates tasks effectively.

5. Run the agent:

npx agent-run @ceo

6. Give it a task by creating @ceo/ceo_feedback.md:

Please create a product roadmap for Q1 2025.

The agent will wake up, process the task, and write results to @ceo/ceo_report.md!

📖 How it works

Directories prefixed with @ are agent workspaces. Agents are arranged in a parent-child tree and communicate through two files:

• {name}_feedback.md — parent writes tasks/instructions to child
• {name}_report.md — child writes results back to parent

Each agent has a .agent/ folder containing its identity, personality, memory, and tool definitions. The scheduler watches these files and wakes the right agent when something changes.

@ceo/
  ceo_feedback.md       ← receives tasks from above
  ceo_report.md         ← reports results upward
  .agent/
    IDENTITY.md
    SOUL.md
    MEMORY.md
  @cto/
    cto_feedback.md
    cto_report.md
    .agent/
      ...
    @backend/
      ...

Trigger rules

| Event | Action | |-------|--------| | {name}_feedback.md written with content | Wake that agent | | {name}_report.md written with content | Wake the parent agent | | New @name/ directory created | Register agent, start watching | | @name/ directory deleted | Unregister agent |

Agent loop

Each time an agent is woken:

1. Build context from .agent/IDENTITY.md, SOUL.md, MEMORY.md + feedback + children's reports
2. Call LLM with a file tool set (read_file, write_file, list_dir, write_report, write_feedback)
3. Execute tool calls until LLM stops
4. Update .agent/MEMORY.md with current task state

Permissions are enforced at the tool layer — agents cannot read each other's memory or write to files they don't own.

Build

npm install
npm run build       # compiles src/ → dist/
npm test            # run unit tests

Requires Node.js 20+.

Run

Option 1: Using npx (recommended)

# Set your API key
export ANTHROPIC_API_KEY=sk-ant-...

# Run from any agent directory
npx agent-run @ceo

Option 2: After global install

npm install -g creworg
agent-run @ceo

Option 3: From source

npm install
npm run build
node dist/cli/cli.js @ceo

Optional flags:

agent-run @ceo --model claude-opus-4-6

The terminal shows a live tree view:

@ceo [thinking]
├── @cto [running: write_feedback]
│   ├── @backend [done]
│   └── @frontend [idle]
└── @pm [done]

Press Ctrl+C to shut down gracefully.

Project structure

org-agent/
├── src/
│   ├── core/       scheduler, agent-runner, types
│   ├── tools/      tools, prompt builder
│   ├── history/    conversation history, compactor
│   ├── skills/     skill loader
│   ├── hooks/      hook registry, loader, types
│   └── cli/        CLI entry point, TUI renderer
├── tests/          unit tests (mirrors src/ structure)
├── hooks/          project-level hooks
├── skills/         project-level skills
├── examples/@ceo   example agent workspace
└── docs/           design documents

Skills

Skills are reusable instructions injected into an agent's system prompt. They describe how to perform a specific task (e.g. "how to write a git commit", "how to run tests").

Installing skills with agent-skill

Skills are distributed via clawhub. Use the agent-skill CLI to install them:

# Install project-level (available to all agents)
agent-skill install <slug>

# Install agent-level (only for a specific agent)
agent-skill install <slug> --agent @ceo

# Install a specific version
agent-skill install <slug> --version 1.2.3

# Overwrite an existing installation
agent-skill install <slug> --force

Project-level skills are placed in skills/{slug}/. Agent-level skills go into @agent/.agent/skills/{slug}/ and the skill name is automatically added to that agent's .agent/TOOLS.md.

Structure

skills/{name}/
  └── SKILL.md    # frontmatter with name + description, body is the instruction text

---
name: git-commit
description: "How to create a well-formed git commit"
---

Always write commit messages in imperative mood...

Enabling skills for an agent

For project-level skills, declare which ones an agent can use in .agent/TOOLS.md:

## Skills

- git-commit
- run-tests

The skill content is appended to the agent's system prompt at runtime. Agent-level skills (.agent/skills/{name}/) take priority over project-level skills (skills/{name}/).

Hooks

Hooks let you run custom logic at specific points during agent execution — without modifying core code.

Events

| Event | When | |-------|------| | scheduler:start | Scheduler starts up (once) | | agent:loop_start | Before each agent loop begins | | agent:loop_end | After each agent loop completes | | agent:tool_result | Each time an agent calls a tool |

Structure

hooks/{name}/
  ├── HOOK.md       # declares name and subscribed events
  └── handler.js    # handler (export default async function)

---
name: my-hook
description: "..."
metadata:
  {
    "events": ["agent:loop_start", "agent:loop_end"]
  }
---

export default async function handler(event) {
  console.log(event.type, event.agent?.name);
}

Handler event data

event.type        — event type string
event.agent       — AgentNode (null for scheduler:start)
event.trigger     — what woke the agent: "feedback" | "report" | "start"
event.toolName    — tool name (agent:tool_result only)
event.timestamp   — Date

Priority

Agent-private hooks (.agent/hooks/{name}/) override project-level hooks (hooks/{name}/) of the same name. Other project-level hooks are unaffected.

Key design decisions

File system as source of truth. All agent state lives in files. The event system is only used for real-time TUI updates — restart the scheduler at any time and it picks up exactly where it left off.

Targeted file watching. The scheduler watches only {name}_feedback.md and {name}_report.md per agent, plus each agent directory (depth 0) for new child detection. This avoids EMFILE errors when agents run npm install or generate large amounts of output.

Single process, async concurrency. All agents run as async coroutines in one Node.js process. No subprocesses, no IPC.

Portable agent identity. An agent's entire state is in its .agent/ folder. Move it to a different workspace and the agent carries its memory and personality with it.