AgentBox

Portable AI agent configuration packaging and sharing tool

AgentBox packages your AI agent's complete environment (settings, skills, memory, sessions) into a single portable file that can be shared across projects, machines, and teams.

English | 简体中文

What Problem Does It Solve?

When working with AI agents like Claude Code, you accumulate valuable context:

• Custom skills and workflows
• Project instructions (CLAUDE.md)
• Memory and conversation history
• MCP server configurations
• Plugin settings

The problem: This context is trapped on your machine. Moving to a new project, sharing with teammates, or migrating to a new computer means starting from scratch.

The solution: AgentBox packages everything into one .agentbox file that you can share, backup, or import anywhere.

Core Features

📦 Export

Package your entire agent environment in one command:

npx @nuomiji/agentbox@latest export --output my-agent.agentbox

Creates a portable bundle containing:

• Project instructions (CLAUDE.md)
• Settings and plugins
• Skills metadata
• Memory files
• Recent conversation history (last 5 messages)
• MCP configurations

📥 Import

Import someone else's agent configuration:

npx @nuomiji/agentbox@latest import my-agent.agentbox

The bundle is unpacked to .agentbox/ with AI-friendly preview files in .agentbox/preview/ showing:

• Recent messages and plans
• Memory excerpts
• Settings overview

🔒 Security

Automatic redaction of sensitive data:

• API keys → {{BINDING_NAME}}
• Absolute paths → {{HOME}}, {{PROJECT_ROOT}}
• Tokens and secrets → Redacted

Check what was redacted: .agentbox/meta/security-audit.json

Use Cases

Team Onboarding

# Share your proven setup with new team members
npx @nuomiji/agentbox@latest export --output team-config.agentbox

Machine Migration

# Old machine
npx @nuomiji/agentbox@latest export --output my-setup.agentbox

# New machine
npx @nuomiji/agentbox@latest import my-setup.agentbox

Configuration Backup

npx @nuomiji/agentbox@latest export --output backup-$(date +%Y%m%d).agentbox

Safe Experimentation

# Save current state
npx @nuomiji/agentbox@latest export --output baseline.agentbox

# Try changes...

# Restore if needed
npx @nuomiji/agentbox@latest import baseline.agentbox

AI Assistant Integration

AgentBox includes a skill that teaches AI assistants to use it automatically.

Install the skill:

Use npx skills command for one-click installation:

npx skills add https://github.com/1zhangyy1/agentbox --skill agentbox

Or install manually:

git clone https://github.com/1zhangyy1/agentbox.git
cp -r agentbox/skills/agentbox /path/to/your/project/.claude/skills/

Once installed, just say:

• "Export my current setup"
• "Import that agent config"
• "What's in this agentbox file?"

The AI will automatically use AgentBox commands.

Installation

No installation needed - run directly with npx:

npx @nuomiji/agentbox@latest export --output my-agent.agentbox
npx @nuomiji/agentbox@latest import my-agent.agentbox

This always uses the latest version.

What Gets Captured

The .agentbox File Format

An .agentbox file is a portable ZIP archive (typically 1-10MB) containing your complete agent environment:

example.agentbox (ZIP archive)
├── box.yaml                      # Bundle metadata
├── bindings.template.env         # Template for API keys/secrets
├── layers/                       # Configuration layers
│   ├── profile.yaml             # CLAUDE.md instructions
│   ├── skills.yaml              # Installed skills
│   ├── memory.yaml              # Memory files
│   ├── plugins.yaml             # Plugin settings
│   ├── session.yaml             # Session metadata
│   └── ...                      # Other settings
├── session/                      # Conversation history
│   ├── transcripts/             # Full conversation logs (.jsonl)
│   └── plans/                   # Plan files (.md)
├── meta/
│   └── security-audit.json      # What was redacted
└── resolved.yaml                 # Merged configuration

Key features:

• Portable: Single file, easy to share via email, Slack, or Git
• Secure: API keys and paths automatically redacted
• Complete: Everything needed to recreate your agent environment
• Human-readable: Unzip to inspect contents (YAML + Markdown)

After import, you get:

your-project/
├── .agentbox/                    # Unpacked bundle
│   ├── preview/                 # AI-friendly summaries
│   │   ├── session.md          # Recent messages & plans
│   │   ├── memory.md           # Memory excerpts
│   │   ├── settings.json       # Settings overview
│   │   └── profile.md          # Instructions preview
│   ├── layers/                  # Raw configuration
│   └── session/                 # Full transcripts
├── CLAUDE.md                     # Imported (if not exists)
└── .claude/settings.local.json   # Merged settings

File Structure After Import

The .agentbox/preview/ directory contains AI-friendly summaries that help you understand what was imported without reading raw YAML files.

Requirements

• Node.js >= 22.0.0
• Claude Code (currently supported host)

Development

git clone https://github.com/1zhangyy1/agentbox.git
cd agentbox
npm install
npm run build

Roadmap

🚀 Coming Soon

Multi-Platform Support

• Codex Adapter - Support configuration import/export for Codex platform
• OpenClaw Adapter - Support configuration conversion for OpenClaw platform
• Cross-Platform Migration - Seamlessly migrate agent configurations between different AI platforms

Goal: Make AgentBox the true cross-platform agent configuration standard, allowing you to easily migrate and share your agent environment regardless of which AI platform you use.

Links

• npm: @nuomiji/agentbox
• GitHub: 1zhangyy1/agentbox
• Issues: Report bugs

License

MIT © zhangyy