Vivian

Vivian is a NanoClaw based autonomous agent (an agent meant to run on its own without human supervision or human invocation). Vivian wraps around Codex, unlike NanoClaw, which used Claude Code.

Quick Start

git clone <your-repo-url>
cd vivian
bash setup.sh
npx tsx setup/index.ts --step environment
npx tsx setup/index.ts --step container -- --runtime docker

Then have Codex run the setup flow in .agents/skills/setup/SKILL.md, or run the remaining setup steps manually from that file (channel auth, registration, mounts, service, verify).

Note: Skills are stored in .agents/skills/. In this Codex branch, apply channel skills with npx tsx scripts/apply-skill.ts .agents/skills/<skill-name> (for example add-whatsapp), then run the corresponding setup/index.ts --step ... commands.

Philosophy

Small enough to understand. One process, a few source files and no microservices. If you want to understand the full NanoClaw codebase, ask your coding agent to walk you through it.

Secure by isolation. Agents run in Linux containers (Apple Container on macOS, or Docker) and they can only see what's explicitly mounted. Bash access is safe because commands run inside the container, not on your host.

Built for the individual user. NanoClaw isn't a monolithic framework; it's software that fits each user's exact needs. Instead of becoming bloatware, NanoClaw is designed to be bespoke. You make your own fork and have Codex modify it to match your needs.

Customization = code changes. No configuration sprawl. Want different behavior? Modify the code. The codebase is small enough that it's safe to make changes.

AI-native.

• No installation wizard; the coding agent guides setup.
• No monitoring dashboard; ask the agent what's happening.
• No debugging tools; describe the problem and the agent fixes it.

Skills over features. Instead of adding features (e.g. support for Telegram) to the codebase, contributors submit skills like /add-telegram that transform your fork. You end up with clean code that does exactly what you need.

Best harness, best model. This experimental branch runs Codex in the container harness for coding and problem-solving tasks, and is designed to be modified by the agent as you customize your fork.

What It Supports

• Multi-channel messaging - Talk to your assistant from WhatsApp, Telegram, Discord, Slack, or Gmail. Add channels with skills like /add-whatsapp or /add-telegram. Run one or many at the same time.
• Isolated group context - Every group gets base context from root SOUL.md, can add group-specific context via groups/{group}/SOUL.md, and runs in its own container sandbox with isolated workspace mounts.
• Main channel - Your private channel (self-chat) for admin control; every group is completely isolated
• Scheduled tasks - Recurring jobs that run the agent and can message you back
• Web access - Search and fetch content from the Web
• Container isolation - Agents are sandboxed in Apple Container (macOS) or Docker (macOS/Linux)
• Agent Swarms - Spin up teams of specialized agents that collaborate on complex tasks. NanoClaw is the first personal AI assistant to support agent swarms.
• Optional integrations - Add Gmail (/add-gmail) and more via skills

Usage

Talk to your assistant with the trigger word (default: @Vivian):

@Vivian send an overview of the sales pipeline every weekday morning at 9am (has access to my Obsidian vault folder)
@Vivian review the git history for the past week each Friday and update the README if there's drift
@Vivian every Monday at 8am, compile news on AI developments from Hacker News and TechCrunch and message me a briefing

From the main channel (your self-chat), you can manage groups and tasks:

@Vivian list all scheduled tasks across groups
@Vivian pause the Monday briefing task
@Vivian join the Family Chat group

Run and Control NanoClaw

On Linux (systemd --user), use:

# Start
systemctl --user start nanoclaw

# Stop
systemctl --user stop nanoclaw

# Restart
systemctl --user restart nanoclaw

# Status
systemctl --user status nanoclaw --no-pager -n 40

# Logs
tail -f logs/nanoclaw.log

# Full agent audit log (daily, all groups)
tail -f data/vivian-audit/$(date +%F).log

After code changes (single command):

npm run rebuild

Optional fast path (skip container rebuild when only host TS changed):

bash scripts/rebuild-nanoclaw.sh --skip-container

Customizing

NanoClaw doesn't use configuration files. To make changes, just tell Codex what you want:

• "Change the trigger word to @Bob"
• "Remember in the future to make responses shorter and more direct"
• "Add a custom greeting when I say good morning"
• "Store conversation summaries weekly"

Or run /customize for guided changes.

The codebase is small enough that the agent can safely modify it.

Contributing

Don't add features. Add skills.

If you want to add Telegram support, don't create a PR that adds Telegram alongside WhatsApp. Instead, contribute a skill file (.agents/skills/add-telegram/SKILL.md) that teaches the coding agent how to transform a NanoClaw installation to use Telegram.

Users then run /add-telegram on their fork and get clean code that does exactly what they need, not a bloated system trying to support every use case.

RFS (Request for Skills)

Skills we'd like to see:

Communication Channels

• /add-signal - Add Signal as a channel

Session Management

• /clear - Add a /clear command that compacts the conversation (summarizes context while preserving critical information in the same session).

Requirements

• macOS or Linux
• Node.js 20+
• Codex CLI (host-side, optional but recommended for guided setup/customization)
• Apple Container (macOS) or Docker (macOS/Linux)

Architecture

Channels --> SQLite --> Polling loop --> Container (Codex runtime) --> Response

Single Node.js process. Channels are added via skills and self-register at startup — the orchestrator connects whichever ones have credentials present. Agents execute in isolated Linux containers with filesystem isolation. Only mounted directories are accessible. Per-group message queue with concurrency control. IPC via filesystem.

For the full architecture details, see docs/SPEC.md.

Key files:

• src/index.ts - Orchestrator: state, message loop, agent invocation
• src/channels/registry.ts - Channel registry (self-registration at startup)
• src/ipc.ts - IPC watcher and task processing
• src/router.ts - Message formatting and outbound routing
• src/group-queue.ts - Per-group queue with global concurrency limit
• src/container-runner.ts - Spawns streaming agent containers
• src/task-scheduler.ts - Runs scheduled tasks
• src/db.ts - SQLite operations (messages, groups, sessions, state)
• SOUL.md - Base behavior/memory loaded for all groups
• groups/*/SOUL.md - Per-group memory

FAQ

Why Docker?

Docker provides cross-platform support (macOS, Linux and even Windows via WSL2) and a mature ecosystem. On macOS, you can optionally switch to Apple Container via /convert-to-apple-container for a lighter-weight native runtime.

Can I run this on Linux?

Yes. Docker is the default runtime and works on both macOS and Linux. Run the setup steps from .agents/skills/setup/SKILL.md.

Is this secure?

Agents run in containers, not behind application-level permission checks. They can only access explicitly mounted directories. You should still review what you're running, but the codebase is small enough that you actually can. See docs/SECURITY.md for the full security model.

Why no configuration files?

We don't want configuration sprawl. Every user should customize NanoClaw so that the code does exactly what they want, rather than configuring a generic system. If you prefer having config files, you can ask the coding agent to add them.

Can I use third-party or open-source models?

Yes. NanoClaw supports any API-compatible model endpoint. Set these environment variables in your .env file:

OPENAI_API_KEY=your-token-here
OPENAI_BASE_URL=https://your-api-endpoint.com

This allows you to use:

• Local models via Ollama with an API proxy
• Open-source models hosted on Together AI, Fireworks, etc.
• Custom model deployments with OpenAI-compatible APIs

Note: The model endpoint must support the OpenAI API format for best compatibility.

How do I debug issues?

Ask Codex. "Why isn't the scheduler running?" "What's in the recent logs?" "Why did this message not get a response?" That's the AI-native approach that underlies NanoClaw.

Why isn't the setup working for me?

If you have issues, ask Codex to run the diagnostics from .agents/skills/debug/SKILL.md and repair failures step-by-step. If you find an issue that is likely affecting other users, open a PR to modify the setup skill instructions.

What changes will be accepted into the codebase?

Only security fixes, bug fixes, and clear improvements will be accepted to the base configuration. That's all.

Everything else (new capabilities, OS compatibility, hardware support, enhancements) should be contributed as skills.

This keeps the base system minimal and lets every user customize their installation without inheriting features they don't want.

Changelog

See CHANGELOG.md for breaking changes and migration notes.

License

MIT