creworg

An AI agent organization framework. Create autonomous companies where AI agents collaborate as Board, CEO, HR, engineers, and more — communicating through files, managed by an HR agent that builds and optimizes the team.

How It Works

Your directory tree IS your organization. Agents communicate by reading and writing markdown files. The Board auto-kicks off the CEO on startup. HR runs on a timer, auditing all agents, creating new ones, and proposing changes through the configured governance mode.

@acme/                              # Board of Directors (org root)
├── .agent/
│   ├── IDENTITY.md                 # name: acme, display_name: Board of Directors, emoji: 🏛️
│   ├── SOUL.md                     # Strategic mandate
│   └── MEMORY.md                   # Company profile (mission, goal, culture)
├── acme_feedback.md                # Human operator writes here to direct the Board
├── acme_report.md                  # Board reports back to operator
├── @ceo/                           # CEO agent
│   ├── .agent/
│   │   ├── IDENTITY.md             # name: ceo, display_name: Sam Will, emoji: 👔, role: Chief Executive Officer
│   │   ├── SOUL.md                 # Strategic leadership principles
│   │   └── MEMORY.md               # Strategic plans and progress
│   ├── ceo_feedback.md             # Tasks from Board
│   ├── ceo_report.md               # Results to Board
│   └── @engineer/                  # Engineer (created by HR on request)
│       ├── .agent/
│       │   ├── IDENTITY.md         # display_name: Alex Chen, emoji: 💻
│       │   └── SOUL.md
│       ├── engineer_feedback.md
│       └── engineer_report.md
└── @hr/                            # HR Director (admin agent, timer-based)
    ├── .agent/
    │   ├── IDENTITY.md
    │   ├── SOUL.md                 # Audit, diagnose, create agents
    │   └── config.json             # { isAdmin: true, timerInterval: 600, soulModifyCooldownRuns: 3, governanceMode: "direct"|"pr" }
    ├── hr_feedback.md
    └── hr_report.md

Quick Start

Install

npm install -g creworg

Initialize an Organization

agent-org-init --name mycompany /path/to/project

The interactive CLI walks you through:

1. Company profile — mission, goal, culture
2. Display names — give CEO and HR human names (e.g. "Sam Will", "Lisa Chen")
3. Governance mode — Direct (immediate changes) or PR Review (GitHub PRs for your approval)
4. Structure — Quick Start template (Flat/Functional/Matrix) or describe custom needs
5. HR bootstrap — HR agent runs, creates agents per template/description with tailored SOULs, writes org report
6. Confirm — review the structure; on confirm, git init + commit structure files + connect GitHub remote

Run the Organization

export ANTHROPIC_API_KEY=sk-ant-...
agent-run /path/to/project/@mycompany

On startup, if the Board's feedback file has content, the Board agent runs immediately — reading the company profile from MEMORY, giving the CEO a strategic directive, then entering delegated status while the CEO works. HR fires on its timer to audit all agents.

TUI Dashboard

🏛️ @mycompany (Board of Directors) — Board of Directors [delegated]
├── 👔 @ceo (Sam Will) — Chief Executive Officer [running: write_feedback]
│   ├── 💻 @engineer (Alex Chen) — Full-Stack Engineer [thinking...]
│   └── 🎨 @designer (Jordan Kim) — UX Designer [idle]
└── 🏢 @hr (Lisa Chen) — HR Director [done]

Format: {emoji} @{name} ({displayName}) — {role} [{status}]

Agent Lifecycle

1. Trigger — feedback file changes, child report written, or timer fires
2. Think — reads SOUL, MEMORY, feedback, child reports; builds context
3. Act — uses tools: read/write files, delegate to children, create agents
4. Report — writes results via write_report (wakes parent agent)
5. Delegated — agent has assigned work to children and is waiting; not yet done
6. Sleep — waits for next trigger (file watch or timer)

Agents resume automatically on restart: if feedback is newer than report, they re-run.

Key Concepts

Board Agent

The org root (@mycompany/) is the Board of Directors. It holds the company profile in MEMORY, gives the CEO strategic directives, evaluates reports, and course-corrects. Humans interact with the Board by writing to mycompany_feedback.md. The Board is the bridge between human intent and autonomous execution.

HR Agent

HR runs on a configurable timer (default: 10 minutes) and autonomously:

• Audits all agents recursively (healthy / stale / stuck / erroring)
• Diagnoses and recovers broken chains — re-sends feedback to stuck agents, escalates to report if stuck 2+ cycles
• Creates agents when the org needs new capabilities ("hiring" = calling create_agent with a tailored SOUL)
• Proposes SOUL/IDENTITY changes via write_agent_file (direct write or PR, per governance mode)
• Manages cooldown — won't modify the same agent's SOUL again until it has run soulModifyCooldownRuns times (default: 3)
• Git pull + PR gate — at the start of every audit cycle, runs git pull and checks for open PRs; will not make further changes while any of its PRs remain open
• Forbidden from merging — HR must not run git merge, gh pr merge, or any command that merges its own PRs; only the human operator can approve and merge

CEO SOUL

The CEO SOUL explicitly states that the team members are AI agents, not humans. "Hiring" means requesting HR to create a new agent. The CEO delegates tasks to direct reports via write_feedback, tracks progress via write_report from subordinates, and enters delegated status while waiting.

Governance Modes

Set in HR's .agent/config.json:

{ "governanceMode": "direct" }
{ "governanceMode": "pr" }

Direct mode: create_agent and write_agent_file write to the local filesystem immediately. The scheduler picks up new agent directories via file watching.

PR mode: Changes are created in a git worktree on a new branch, pushed to origin, and a GitHub PR is opened via gh pr create. The local working directory (main) is never touched. The PR body includes the reason, display name, and role. The worktree and local branch are cleaned up after push. Changes appear in the live org only after the human merges the PR and the scheduler pulls (automatic on next timer tick).

IDENTITY.md Format

# Identity

name: engineer
display_name: Alex Chen
emoji: 💻
role: Full-Stack Engineer

display_name is required when calling create_agent — every agent must have a human name. The scheduler hot-reloads IDENTITY.md when it changes, updating the TUI immediately without restart.

Agent Statuses

| Status | Meaning | |--------|---------| | idle | No pending work | | thinking | LLM is generating a response | | running | Executing a tool call | | waiting for feedback | Wrote report, waiting for parent to respond | | delegated | Assigned work to children, waiting for their reports | | done | Completed all work | | error | Consecutive errors; scheduler retries up to maxRetries |

CLI Commands

agent-org-init

Interactive organization setup:

agent-org-init --name mycompany /path/to/project
agent-org-init --name mycompany       # defaults to current directory
agent-org-init                        # org name defaults to "org"

agent-org-create

Create a single agent imperatively:

agent-org-create @designer --parent /path/to/@ceo --role "UX Designer"
agent-org-create @admin --parent /path/to/@org --admin --timer 600
agent-org-create @analyst --parent /path/to/@ceo --identity ./identity.md --soul ./soul.md

Flags: --parent <path> (required), --role "description", --identity <path>, --soul <path>, --admin, --timer <seconds>

agent-run

Run an organization (starts the scheduler + TUI):

agent-run /path/to/@mycompany
agent-run /path/to/@mycompany --model claude-opus-4-5

agent-skill

Manage agent skills:

agent-skill install my-skill

Agent Tools

All agents:

| Tool | Scope | Description | |------|-------|-------------| | read_file | Any file | Read files (no restriction) | | write_file | Own directory | Write within workspace; cannot write own report/feedback or another agent's .agent/ | | delete_path | Own directory | Delete files/dirs within workspace | | list_dir | Any directory | List contents; agent subdirs tagged [agent] | | write_report | Own report | Write results; triggers parent agent | | write_feedback | Direct children | Delegate tasks to child agents | | run_command | Shell | Execute shell commands | | memory_search | Own .agent/ | Search memory files | | memory_get | Own .agent/ | Read MEMORY.md or a daily note | | memory_write | Own .agent/ | Append or overwrite MEMORY.md or daily note |

Admin-only tools (HR and any agent with isAdmin: true):

| Tool | Description | |------|-------------| | write_agent_file | Write to any agent's .agent/ files (SOUL.md, IDENTITY.md). Requires reason. Direct or PR per governance mode. Cannot modify own .agent/. | | write_feedback_any | Send feedback to any registered agent, not just direct children | | create_agent | Create new agent with IDENTITY.md, SOUL.md, MEMORY.md. Requires display_name and reason. Direct or PR per governance mode. | | archive_agent | Archive an agent directory via PR | | check_pending_prs | Check for open PRs authored by this agent |

Organization Templates

| Template | Structure | Best For | |----------|-----------|----------| | Flat | Board + CEO + HR | Small teams, fast execution | | Functional | Board + CEO + CTO/CMO + HR | Specialized departments | | Matrix | Board + CEO + CTO/CMO/CFO + HR | Complex organizations |

Templates define the initial structure. HR creates all agents with human display names and SOULs tailored to the company profile during agent-org-init.

Configuration

Environment Variables

ANTHROPIC_API_KEY=sk-ant-...       # Required
ANTHROPIC_BASE_URL=https://...     # Optional: custom API endpoint
BRAVE_API_KEY=...                  # Optional: web search capability

Agent Config (config.json)

{
  "isAdmin": true,
  "timerInterval": 600,
  "soulModifyCooldownRuns": 3,
  "governanceMode": "direct"
}

| Field | Type | Description | |-------|------|-------------| | isAdmin | boolean | Grants admin tools: write_agent_file, write_feedback_any, create_agent, archive_agent, check_pending_prs | | timerInterval | number | Seconds between timer wakeups (HR default: 600) | | soulModifyCooldownRuns | number | Min runs before re-modifying same agent's SOUL (HR default: 3) | | governanceMode | "direct" | "pr" | How HR applies structural changes |

Development

git clone https://github.com/Adamlixi/creworg.git
cd creworg
npm install
npm run build
npm test            # 450 tests
npm run dev         # Watch mode
npm link            # Link CLI commands globally

Architecture

src/
├── cli/
│   ├── cli.ts              # agent-run entry point (Scheduler + TUI)
│   ├── org-init-cli.ts     # agent-org-init: interactive setup, Board/CEO/HR SOULs, HR bootstrap, git init
│   ├── org-create-cli.ts   # agent-org-create: single agent creation
│   ├── tui.ts              # ANSI tree renderer: emoji @name (displayName) — role [status]
│   └── skill-cli.ts        # agent-skill
├── core/
│   ├── scheduler.ts        # File watching (chokidar), trigger routing, delegated status, IDENTITY.md hot-reload, git pull on timer
│   ├── agent-runner.ts     # LLM loop (pi-agent-core agentLoop), session-based history
│   ├── agent-creator.ts    # Atomic agent creation (mkdtemp → populate → rename)
│   └── types.ts            # AgentNode (displayName/role/emoji/governanceMode), AgentStatus, AgentTrigger
├── tools/
│   ├── tools.ts            # All tool definitions; create_agent and write_agent_file handle direct vs PR mode
│   ├── git.ts              # Worktree-based PR creation: branch, copy, commit, push, gh pr create, cleanup
│   ├── prompt.ts           # System prompt builder
│   └── templates.ts        # Flat / Functional / Matrix org templates
├── history/                # Conversation history management
├── session/                # Session memory and compaction
└── hooks/                  # Event hook system (scheduler:start, agent lifecycle)

License

MIT