Installation

UFOO requires Node.js 18 or higher.

$ npm install -g u-foo

Or use without installing:

$ npx u-foo

Verify installation:

$ ufoo --version
1.6.0

$ ufoo doctor
✓ Node.js v22.x detected
✓ u-foo@1.6.0 installed globally
✓ claude CLI found
✓ codex CLI found

Quick Start

Two steps to multi-agent collaboration:

$ cd your-project
$ ufoo init
✓ Created .ufoo/
✓ Bus initialized
✓ Context ready

# Terminal 1 - Launch Claude as project manager
$ uclaude --nickname pm

# Terminal 2 - Launch Codex as developer
$ ucodex --nickname dev

# They auto-discover each other via the bus
[ubus] @pm ↔ @dev routing enabled

Global Chat ufoo -g

Use ufoo -g (or ufoo --global) to launch a cross-project chat dashboard. Instead of being scoped to a single project, global mode connects to all running ufoo daemons and lets you switch between projects on the fly.

Quick Start

$ ufoo -g
[global] Connected to 3 project daemons

> /project list
  1. ~/Code/api-server    (2 agents online)
  2. ~/Code/web-app       (1 agent online)
  3. ~/Code/ml-pipeline   (3 agents online)

> /project switch 2
✓ Switched to ~/Code/web-app

> /launch claude scope=inplace
> @claude-1 Review the login page component

Global Chat Commands

How It Works

• Global mode scans ~/.ufoo/chat/ for registered project daemons
• Chat history and input history are stored per-project under the global directory
• Switching projects reconnects the chat UI to the target project's daemon
• All standard chat commands (/agents, @nickname, /bus) work within the active project scope

Architecture

UFOO creates a shared workspace layer between AI agents:

  uclaude          ucodex          ucode
     |                |                |
     └────────────────┬────────────────┘
                      |
               ufoo bus       Event Bus
                      |
         ┌────────────┼────────────┐
         |            |            |
    .ufoo/bus    context    decisions

Data Flow

CLI Reference

All available ufoo commands:

Core Commands

Bus Commands

Context Commands

Daemon Commands

Skills Commands

uclaude

Wrapper around Claude Code CLI with automatic workspace integration.

$ uclaude [options]

Options:
  --nickname <name>   Set agent nickname (e.g. pm, dev, reviewer)
  --resume            Resume previous session
  --internal          Run in headless/internal mode

What uclaude does automatically

• Runs ufoo init if workspace not initialized
• Joins the event bus with the given nickname
• Injects bus probe after Claude is ready (via PTY wrapper)
• Monitors parent-child process relationships
• Maintains isolated session IDs per agent type

ucodex

Wrapper around OpenAI Codex CLI with identical workspace integration.

$ ucodex [options]

Options:
  --nickname <name>   Set agent nickname
  --resume            Resume previous session

Works exactly like uclaude but launches the Codex CLI instead.

ucode

Built-in self-developed coding agent. Supports multi-turn conversations, streaming output, and native tool execution (read, write, edit, bash).

$ ucode

Options:
  --tui               Launch interactive TUI mode (default)
  --provider <name>   Set LLM provider (openai, anthropic)
  --model <name>      Set model name
  --resume <id>       Resume a previous session

ucode joins the workspace bus automatically and can receive tasks from other agents via /ubus.

Event Bus

The bus is how agents talk to each other. Messages are stored in .ufoo/bus/ as flat files — no database, no server.

How It Works

# Agent "pm" sends a message to agent "dev"
$ ufoo bus send dev "Please review src/auth.js"

# Agent "dev" checks for messages
$ ufoo bus check dev
[1] from @pm: Please review src/auth.js

# In-agent: the /ubus skill auto-polls and executes

Bus Storage

.ufoo/bus/
├── events/       # Append-only event log
├── queues/       # Per-agent message queues
└── offsets/      # Read position tracking

Smart Routing

Agents resolve nicknames to IDs automatically. The bus supports:

• Direct messaging between agents
• Broadcast to all connected agents
• Nickname-based routing (e.g. @pm, @dev)
• Auto-acknowledgment of received messages

Context & Decisions

Shared project knowledge that persists across sessions and agents.

Decisions

When agents make architectural or implementation decisions, they record them:

# List all decisions
$ ufoo ctx decisions -l

[001] Use JWT for auth tokens
[002] PostgreSQL as primary database
[003] TailwindCSS for styling

# View latest decision
$ ufoo ctx decisions -n 1

Decision Storage

Decisions are stored as markdown files in .ufoo/context/decisions/ — fully git-friendly. Commit them alongside your code for full traceability.

Daemon

Background process that monitors the bus and bridges agent communication.

# Start daemon
$ ufoo daemon --start
✓ Daemon started (pid: 12345)

# Check status
$ ufoo daemon --status
running pid:12345 uptime:2m

# Stop daemon
$ ufoo daemon --stop
✓ Daemon stopped

Single Daemon Guarantee

Only one daemon instance runs per workspace. The system detects and prevents duplicate daemons, resolving the multi-daemon conflicts present in earlier versions.

Skills

Extensible agent capabilities defined as markdown files. Agents discover and execute them via slash commands.

Built-in Skills

Custom Skills

Place markdown files in SKILLS/<name>/SKILL.md to define custom skills. Agents discover them automatically via ufoo skills list.

PTY Wrapper

Terminal emulation layer that wraps agent processes for intelligent interaction.

What It Does

• Spawns agents inside a pseudo-terminal (via node-pty)
• Captures and analyzes terminal output in real-time
• Injects bus probe commands after agent initialization
• Handles terminal resize, signals, and lifecycle

Smart Probe Injection

Instead of injecting commands immediately (which may fail if the agent isn't ready), the PTY wrapper waits for the ReadyDetector signal before sending the session probe.

Ready Detection

The ReadyDetector monitors PTY output to determine when an agent is ready to accept input.

Detection Strategy

Multi-layer fallback:
1. PTY output analysis    10s window - watch for ready patterns
2. Fallback timer         8s after launch - assume ready
3. Retry loop             15 retries max - for slow startups

Performance Metrics

The system tracks detection time and buffer usage for diagnostics. Use ufoo doctor to view readiness statistics.

Project Structure

What ufoo init creates in your project:

your-project/
└── .ufoo/
    ├── agent/
    │   └── all-agents.json    # Agent metadata registry
    ├── bus/
    │   ├── events/            # Append-only event log
    │   ├── queues/            # Per-agent message queues
    │   └── offsets/           # Read position tracking
    ├── context/
    │   ├── decisions/         # Decision records (markdown)
    │   └── decisions.jsonl    # Decision index
    └── daemon/
        └── ...                # Daemon runtime files