ufoo

中文文档

🤖 Multi-agent AI collaboration framework for orchestrating Claude Code, OpenAI Codex, and custom AI agents.

📦 npm: https://www.npmjs.com/package/u-foo

Why ufoo?

ufoo solves the challenge of coordinating multiple AI coding agents:

🔗 Unified Interface - One chat UI to manage all your AI agents
📬 Message Routing - Agents can communicate and collaborate via event bus
🧠 Context Sharing - Shared decisions and knowledge across agents
🚀 Auto-initialization - Agent wrappers handle setup automatically
📝 Decision Tracking - Record architectural decisions and trade-offs
⚡ Real-time Updates - See agent status and messages instantly

Features

Chat Interface - Interactive multi-agent chat UI (ufoo chat)
- Real-time agent communication and status monitoring
- Dashboard with agent list, online status, and quick actions
- Direct messaging to specific agents with @agent-name
Event Bus - Real-time inter-agent messaging (ufoo bus)
Context Sharing - Shared decisions and project context (ufoo ctx)
Agent Wrappers - Auto-initialization for Claude Code (uclaude), Codex (ucodex), and ucode assistant (ucode)
- PTY Wrapper - Intelligent terminal emulation with ready detection
- Smart Probe Injection - Waits for agent initialization before injecting commands
- Consistent Branding - Unified agent naming (e.g., ucode-1, claude-1, codex-1)
Skills System - Extensible agent capabilities (ufoo skills)

Installation

# Install globally from npm (recommended)
npm install -g u-foo

Or install from source:

git clone https://github.com/Icyoung/ufoo.git ~/.ufoo
cd ~/.ufoo && npm install && npm link

After installation, the following commands are available globally: ufoo, uclaude, ucodex, ucode.

Quick Start

# Initialize a project
cd your-project
ufoo init

# Launch chat interface (default command)
ufoo chat
# or just
ufoo

# Use agent wrappers (auto-init + bus join)
uclaude   # Claude Code wrapper
ucodex    # Codex wrapper
ucode     # ucode assistant (self-developed AI coding agent)

Example Workflow

# 1. Start the chat interface
$ ufoo

# 2. Launch agents from chat
> /launch claude
> /launch ucode

# 3. Send tasks to agents
> @claude-1 Please analyze the current codebase structure
> @ucode-1 Fix the bug in authentication module

# 4. Agents communicate via bus
claude-1: Analysis complete. Found 3 areas needing refactoring...
ucode-1: Bug fixed. Running tests...

# 5. Check decisions made
> /decisions

Native self-developed implementation lives under src/code.

Prepare and verify ucode runtime wiring:

ufoo ucode doctor
ufoo ucode prepare
ufoo ucode build

Try native core queue runtime (WIP):

ucode-core submit --tool read --args-json '{"path":"README.md"}'
ucode-core run-once --json
ucode-core list --json

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.

$ ufoo -g

> /project list          # List all running project daemons
> /project switch 2      # Switch to project #2
> /launch claude scope=inplace   # Launch agent in current context
> @claude-1 Start reviewing the auth module

Command	Description
`/project list`	List running projects from global runtime registry
`/project switch <index\|path>`	Switch active project daemon connection
`/launch <agent> scope=inplace`	Launch agent in current workspace
`/launch <agent> scope=window`	Launch agent in separate terminal window

Agent Configuration

Configure AI providers in .ufoo/config.json:

ucode Configuration (Self-developed Assistant)

{
  "ucodeProvider": "openai",          // or "anthropic", "azure", etc.
  "ucodeModel": "gpt-4-turbo-preview",
  "ucodeBaseUrl": "https://api.openai.com/v1",
  "ucodeApiKey": "sk-***"
}

Claude Configuration

{
  "claudeProvider": "claude-cli",     // Uses Claude CLI
  "claudeModel": "claude-3-opus"      // or "claude-3-sonnet"
}

Codex Configuration

{
  "codexProvider": "codex-cli",       // Uses Codex CLI
  "codexModel": "gpt-4"               // or "gpt-4-turbo-preview"
}

Complete Example

{
  "launchMode": "internal",
  "ucodeProvider": "openai",
  "ucodeModel": "gpt-4-turbo-preview",
  "ucodeBaseUrl": "https://api.openai.com/v1",
  "ucodeApiKey": "sk-***",
  "claudeProvider": "claude-cli",
  "claudeModel": "claude-3-opus",
  "codexProvider": "codex-cli",
  "codexModel": "gpt-4"
}

ucode writes these into a global config directory (~/.ufoo/agent/ucode/config) and uses them for native planner/engine calls. Configure once, use across all projects. Project-level .ufoo/config.json can override global settings when needed.

Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   uclaude   │     │   ucodex    │     │  other...   │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │
       └───────────────────┼───────────────────┘
                           │
                    ┌──────▼──────┐
                    │  ufoo bus   │  Event Bus
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
       ┌──────▼──────┐ ┌───▼───┐ ┌──────▼──────┐
       │  .ufoo/bus  │ │context│ │  decisions  │
       └─────────────┘ └───────┘ └─────────────┘

Bus state lives in .ufoo/agent/all-agents.json (metadata), .ufoo/bus/* (queues/events), and .ufoo/daemon/* (bus daemon runtime).

Commands

Core Commands

Command	Description
`ufoo`	Launch chat interface (default)
`ufoo chat`	Launch interactive multi-agent chat UI
`ufoo -g`	Launch global chat mode (cross-project dashboard)
`ufoo init`	Initialize .ufoo in current project
`ufoo status`	Show banner, unread bus messages, open decisions
`ufoo doctor`	Check installation health

Agent Management

Command	Description
`ufoo daemon start`	Start ufoo daemon
`ufoo daemon stop`	Stop ufoo daemon
`ufoo daemon status`	Check daemon status
`ufoo resume [nickname]`	Resume agent sessions

Event Bus

Command	Description
`ufoo bus join`	Join event bus (auto by agent wrappers)
`ufoo bus send <id> <msg>`	Send message to agent
`ufoo bus check <id>`	Check pending messages
`ufoo bus status`	Show bus status and online agents

Context & Decisions

Command	Description
`ufoo ctx decisions -l`	List all decisions
`ufoo ctx decisions -n 1`	Show latest decision
`ufoo ctx decisions new <title>`	Create new decision

Skills

Command	Description
`ufoo skills list`	List available skills
`ufoo skills show <skill>`	Show skill details

Notes:

Claude CLI headless agent uses --dangerously-skip-permissions.

Project Structure

ufoo/
├── bin/
│   ├── ufoo         # Main CLI entry (bash)
│   ├── ufoo.js      # Node wrapper
│   ├── uclaude      # Claude Code wrapper
│   ├── ucodex       # Codex wrapper
│   └── ucode        # ucode assistant wrapper
├── SKILLS/          # Global skills (uinit, ustatus)
├── src/
│   ├── bus/         # Event bus implementation (JS)
│   ├── daemon/      # Daemon + chat bridge
│   ├── agent/       # Agent launch/runtime
│   └── code/        # Native ucode core implementation
├── scripts/         # Legacy helpers (bash, deprecated)
├── modules/
│   ├── context/     # Decision/context protocol
│   ├── bus/         # Bus module resources
│   └── resources/   # UI/icons (optional)
├── AGENTS.md        # Project instructions (canonical)
└── CLAUDE.md        # Points to AGENTS.md

Per-Project Layout

After ufoo init, your project gets:

your-project/
├── .ufoo/
│   ├── bus/
│   │   ├── events/      # Event log (append-only)
│   │   ├── queues/      # Per-agent message queues
│   │   └── offsets/     # Read position tracking
│   └── context/
│       ├── decisions/   # Decision records
│       └── decisions.jsonl  # Decision index
├── scripts/             # Legacy symlink (optional)
├── AGENTS.md            # Injected protocol blocks
└── CLAUDE.md            # → AGENTS.md

Chat Interface

The interactive chat UI provides a centralized hub for agent management:

Features

Real-time Communication - See all agent messages in one place
Agent Dashboard - Monitor online status, session IDs, and nicknames
Direct Messaging - Use @agent-name to target specific agents
Command Completion - Tab completion for commands and agent names
Mouse Support - Toggle with Ctrl+M for scrolling vs text selection
Session History - Persistent message history across sessions

Keyboard Shortcuts

Key	Action
`Tab`	Auto-complete commands/agents
`Ctrl+C`	Exit chat
`Ctrl+M`	Toggle mouse mode
`Ctrl+L`	Clear screen
`Ctrl+R`	Refresh agent list
`↑/↓`	Navigate command history

Chat Commands

Command	Description
`/help`	Show available commands
`/agents`	List online agents
`/clear`	Clear chat history
`/settings`	Configure chat preferences
`@agent-name <message>`	Send to specific agent

Agent Communication

Agents communicate via the event bus:

# Agent A sends task to Agent B
ufoo bus send "codex:abc123" "Please analyze the project structure"

# Agent B checks and executes
ufoo bus check "codex:abc123"
# → Executes task automatically
# → Replies with result
ufoo bus send "claude-code:xyz789" "分析完成：..."

Skills (for Agents)

Built-in skills triggered by slash commands:

/ubus - Check and auto-execute pending messages
/uctx - Quick context status check
/ustatus - Unified status view (banner, unread bus, open decisions)
/uinit - Manual .ufoo initialization

Requirements

macOS - Required for Terminal.app/iTerm2 integration
Node.js >= 18 - For npm installation and JavaScript runtime
Bash 4+ - For shell scripts and command execution
Terminal - iTerm2 or Terminal.app for agent launching

Codex CLI Notes

ufoo chat automatically starts the daemon if not running - no need to run ufoo daemon start separately.

If Codex CLI fails with permission errors under ~/.codex (e.g. sessions dir), set CODEX_HOME to a writable path:

export CODEX_HOME="$PWD/.ufoo/codex"
ufoo chat  # daemon auto-starts

Development

Setup

# Clone the repository
git clone https://github.com/Icyoung/ufoo.git
cd ufoo

# Install dependencies
npm install

# Link for local development
npm link

# Run tests
npm test

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Project Structure

src/ - Core JavaScript implementation
bin/ - CLI entry points
modules/ - Modular features (bus, context, etc.)
test/ - Unit and integration tests
SKILLS/ - Agent skill definitions

License

UNLICENSED (Private)

Name		Name	Last commit message	Last commit date
Latest commit History 114 Commits
SKILLS		SKILLS
bin		bin
landing		landing
modules		modules
scripts		scripts
src		src
templates/groups		templates/groups
test		test
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
README.zh-CN.md		README.zh-CN.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

ufoo

Why ufoo?

Features

Installation

Quick Start

Example Workflow

Global Chat (ufoo -g)

Agent Configuration

ucode Configuration (Self-developed Assistant)

Claude Configuration

Codex Configuration

Complete Example

Architecture

Commands

Core Commands

Agent Management

Event Bus

Context & Decisions

Skills

Project Structure

Per-Project Layout

Chat Interface

Features

Keyboard Shortcuts

Chat Commands

Agent Communication

Skills (for Agents)

Requirements

Codex CLI Notes

Development

Setup

Contributing

Project Structure

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Global Chat (`ufoo -g`)

Packages