# ConnectOnion Documentation

> ConnectOnion is the agent CLI harness. Each `co` command connects your AI agent to one service: Gmail, Outlook, Google Calendar, WhatsApp, Telegram, Discord, Feishu, SMS, a real logged-in browser, Google Drive or a Synology NAS. It also gives the agent its own 0x address and mailbox, and it works from Claude Code and Codex. You don't create an OAuth app, add DNS records or write a Playwright script. It also ships a Python SDK (the Agent class, tools, plugins) for building your own agent. Open source, Apache-2.0.

## Getting Started

- [Complete documentation catalog](https://docs.connectonion.com/docs-index.txt): Every documentation route, description, and available Markdown source; generated with the site.

- [Introduction](https://docs.connectonion.com/): The agent CLI harness, and every co command
- [Quick Start](https://docs.connectonion.com/quickstart): CLI only: install, co init, then connect email, Gmail, a browser, chat apps and Claude Code
- [Vibe Coding Guide](https://docs.connectonion.com/vibe-coding): Use AI tools like Cursor to build agents
- [All co commands](https://docs.connectonion.com/cli): All 42 commands and their subcommands, generated from co commands

## Guides

- [CLI vs MCP for AI agents: why a CLI harness](https://docs.connectonion.com/guides/cli-vs-mcp): MCP loads every tool definition into context up front and skills must be installed per agent; a CLI costs nothing until the agent runs it, and --help is the manual.
- [What is an agent CLI harness?](https://docs.connectonion.com/guides/what-is-an-agent-cli-harness): An agent CLI harness is a set of command-line tools an AI agent runs to reach email, chat apps, a browser, files and servers. How it works, and what ConnectOnion includes.
- [How to give Claude Code or Codex access to Gmail](https://docs.connectonion.com/guides/claude-code-gmail): Connect Gmail to Claude Code or Codex in three commands: pip install connectonion, co auth google, co skills link. No Google Cloud project; credentials stay on your computer.
- [How to give an AI agent access to Gmail and Outlook](https://docs.connectonion.com/guides/ai-agent-gmail): Connect an AI agent to Gmail with co auth google or Outlook with co auth microsoft. No OAuth app to register; the agent reads, searches, sends and replies with co gmail and co outlook.
- [How to give an AI agent its own email address](https://docs.connectonion.com/guides/ai-agent-email-address): co init gives an AI agent its own mailbox at 0x…@mail.openonion.ai with no DNS records or email provider. Send with co email send, read with co email inbox, claim a readable name.
- [How to give an AI agent a real, logged-in browser](https://docs.connectonion.com/guides/ai-agent-browser): co browser keeps one real Chrome open between commands. Log in by hand once, 2FA included, and every later command or co browser task runs in that session. No Playwright script.
- [How to connect an AI agent to WhatsApp](https://docs.connectonion.com/guides/ai-agent-whatsapp): co whatsapp links a number as a companion device by QR, writes every message to ~/.co/inbox/whatsapp/, and lets an agent receive, reply and send from the command line.
- [How to connect an AI agent to Telegram, Discord, Feishu or SMS](https://docs.connectonion.com/guides/ai-agent-chat-apps): Each chat app becomes an inbox of files an agent reads with receive and answers with reply: co telegram, co discord, co feishu, co lark and co sms. The listeners dial out, so no public webhook.
- [How to tell if a CLI works for an AI agent](https://docs.connectonion.com/guides/cli-for-ai-agents): co audit runs any CLI's --help pages and scores them for an agent (1.8.9 preview).

## CLI: connect your agent

- [co init](https://docs.connectonion.com/cli/init): The agent's identity: a keypair and 0x address
- [co auth](https://docs.connectonion.com/cli/auth): Sign in to OpenOnion, or connect Google, Microsoft, Feishu or Lark
- [co email](https://docs.connectonion.com/cli/email): The agent's own mailbox, with no DNS setup
- [co gmail](https://docs.connectonion.com/cli/gmail): Your Gmail account from the terminal
- [co outlook](https://docs.connectonion.com/cli/outlook): Your Outlook mail, contacts and calendar
- [co gcalendar](https://docs.connectonion.com/cli/gcalendar): Google Calendar events and Meet links
- [co whatsapp](https://docs.connectonion.com/cli/whatsapp): WhatsApp as an inbox of files
- [co telegram](https://docs.connectonion.com/cli/telegram): A Telegram bot: send, plus experimental listen, receive and reply
- [co discord](https://docs.connectonion.com/cli/discord): Experimental: a Discord bot as an inbox
- [co feishu](https://docs.connectonion.com/cli/feishu): A Feishu or Lark bot as an inbox
- [co sms](https://docs.connectonion.com/cli/sms): An encrypted SMS inbox from a paired Android phone
- [co browser](https://docs.connectonion.com/cli/browser-command): Drive one persistent, logged-in browser
- [co proxy](https://docs.connectonion.com/cli/proxy): Lend an agent this computer's internet connection
- [co gdrive](https://docs.connectonion.com/cli/gdrive): Google Drive files
- [co syno](https://docs.connectonion.com/cli/synology): A Synology NAS
- [co youtube](https://docs.connectonion.com/cli/youtube): The YouTube Data API
- [co tiktok](https://docs.connectonion.com/cli/tiktok): Experimental: TikTok post plans and read-only readiness
- [co skills](https://docs.connectonion.com/cli/skills): Link ConnectOnion's skills into Claude Code and Codex
- [co rem](https://docs.connectonion.com/rem): stable 1.9.1 memory — a first run that investigates every page in a 180-day map and deepens people with older mail, followed by approved overnight context from mail and coding sessions
- [co benchmark](https://docs.connectonion.com/cli/benchmark): Benchmark a skill, then co eval it on the real agent
- [co audit](https://docs.connectonion.com/cli/audit): Preview (1.8.9): is a CLI fit for an agent harness? Scores its help pages
- [co call](https://docs.connectonion.com/cli/call): Run one command on a remote agent
- [co server](https://docs.connectonion.com/cli/server): Servers you own, for co deploy --to; co server ssh opens a shell
- [co schedule](https://docs.connectonion.com/cli/schedule): The agent's recurring work, from .co/schedule.yaml
- [co ai](https://docs.connectonion.com/cli/ai): Built-in AI coding assistant that understands ConnectOnion
- [co browser](https://docs.connectonion.com/cli/browser-command): Browser automation and screenshot tool
- [co copy](https://docs.connectonion.com/cli/copy): Copy built-in tools, plugins, skills, and prompts to your project for customization

## Core Concepts

- [Agent](https://docs.connectonion.com/agent): Main orchestrator class — LLM calls, tool execution, event system
- [System Prompts](https://docs.connectonion.com/prompts): Define agent personality via string, file, or Path
- [Prompt Formats](https://docs.connectonion.com/prompts/formats): Supported prompt template formats
- [Tools](https://docs.connectonion.com/tools): Functions become tools automatically via type hints and docstrings
- [Models](https://docs.connectonion.com/models): Multi-provider support — OpenAI, Anthropic, Gemini, managed keys (co/)
- [Pricing](https://docs.connectonion.com/models/pricing): Credits, token costs, and managed keys pricing
- [LLM Function](https://docs.connectonion.com/llm_do): One-shot LLM calls without creating an agent
- [Event System](https://docs.connectonion.com/on_events): 12 lifecycle hooks for injecting logic at any execution point
- [Plugin System](https://docs.connectonion.com/plugin): Bundle event handlers into reusable plugins

## Network

- [host()](https://docs.connectonion.com/host): Make your agent remotely callable via HTTP + WebSocket + P2P relay
- [Connect to Agents](https://docs.connectonion.com/connect): Call remote agents as tools
- [Session Reconnect](https://docs.connectonion.com/session-reconnect): WebSocket session recovery and reconnection
- [Threat Model](https://docs.connectonion.com/threat-model): Security considerations for networked agents

## Features

- [Permissions](https://docs.connectonion.com/features/permissions): Unified permission system for tools and commands
- [Skills](https://docs.connectonion.com/features/skills): Reusable workflows with auto permission scoping, Claude Code compatible
- [Audio Transcription](https://docs.connectonion.com/features/transcribe): Speech-to-text via Gemini
- [Trust](https://docs.connectonion.com/features/trust): Multi-agent trust system — open, careful, strict presets

## Useful Tools

- [Overview](https://docs.connectonion.com/useful-tools): All built-in tools
- [Memory](https://docs.connectonion.com/memory): Persistent memory as a tool
- [WebFetch](https://docs.connectonion.com/web-fetch): Web scraping and content extraction
- [Agent Emails](https://docs.connectonion.com/agent-emails): Email send/receive overview
- [Send Email](https://docs.connectonion.com/agent-emails/send): SMTP email sending
- [Receive Emails](https://docs.connectonion.com/agent-emails/receive): IMAP email fetching
- [Gmail](https://docs.connectonion.com/gmail): Gmail OAuth integration with labels, CRM
- [Outlook](https://docs.connectonion.com/outlook): Microsoft Outlook OAuth integration
- [Diff Writer](https://docs.connectonion.com/useful-tools/diff-writer): File writing with human approval
- [Shell](https://docs.connectonion.com/useful-tools/shell): Cross-platform command execution
- [bash](https://docs.connectonion.com/useful-tools/bash): Unix/Mac command execution
- [Slash Command](https://docs.connectonion.com/useful-tools/slash-command): Custom slash commands from markdown
- [Terminal](https://docs.connectonion.com/useful-tools/terminal): Interactive terminal with autocomplete
- [Todo List](https://docs.connectonion.com/useful-tools/todo-list): Task tracking tool
- [FileTools](https://docs.connectonion.com/useful-tools/file-tools): File read/write/edit with safety tracking
- [BrowserAutomation](https://docs.connectonion.com/useful-tools/browser-tools): Natural language browser automation via Playwright
- [Codex](https://docs.connectonion.com/useful-tools/codex): Native Codex app-server delegation with resume and per-action approval

## Integrations

- [Google Integration](https://docs.connectonion.com/google-integration): Gmail + Google Calendar OAuth setup
- [Microsoft Integration](https://docs.connectonion.com/microsoft-integration): Outlook + Microsoft Calendar OAuth setup

## Useful Plugins

- [Overview](https://docs.connectonion.com/useful-plugins): All built-in plugins
- [re_act](https://docs.connectonion.com/useful-plugins/re-act): ReAct reasoning — reflect + plan after each tool call
- [eval](https://docs.connectonion.com/useful-plugins/eval): Task evaluation — judge if task is complete
- [image_result_formatter](https://docs.connectonion.com/useful-plugins/image-result-formatter): Format image results for vision models
- [shell_approval](https://docs.connectonion.com/useful-plugins/shell-approval): CLI approval for shell commands
- [gmail_plugin](https://docs.connectonion.com/useful-plugins/gmail-plugin): Gmail approval flows
- [calendar_plugin](https://docs.connectonion.com/useful-plugins/calendar-plugin): Calendar event approval
- [system_reminder](https://docs.connectonion.com/useful-plugins/system-reminder): Context injection after tool execution
- [prefer_write_tool](https://docs.connectonion.com/useful-plugins/prefer-write-tool): Block bash file writes, prefer FileTools
- [skills](https://docs.connectonion.com/useful-plugins/skills): Skill auto-discovery and permission scoping
- [tool_approval](https://docs.connectonion.com/useful-plugins/tool-approval): Web-based approval UI via WebSocket
- [auto_compact](https://docs.connectonion.com/useful-plugins/auto-compact): Auto-compress context at 90% capacity
- [subagents](https://docs.connectonion.com/useful-plugins/subagents): Spawn sub-agents with independent tools
- [ulw](https://docs.connectonion.com/useful-plugins/ulw): Ultra Light Work — fully autonomous mode
- [ui_stream](https://docs.connectonion.com/useful-plugins/ui-stream): Real-time streaming to web UI

## Useful Skills

Skills are copyable markdown workflows invoked with /skill-name. Install with: co copy <skill-name>

- [Overview](https://docs.connectonion.com/useful-skills): All built-in copyable skills
- [ship-feature](https://docs.connectonion.com/useful-skills/ship-feature): Ship a feature end-to-end — update tests, docs, docs-site, then release to PyPI

## TUI Components

- [Overview](https://docs.connectonion.com/tui): Terminal UI component library
- [pick](https://docs.connectonion.com/tui/pick): Single-select menu
- [Input](https://docs.connectonion.com/tui/input): Text input with autocomplete
- [Dropdown](https://docs.connectonion.com/tui/dropdown): Dropdown selection list
- [StatusBar](https://docs.connectonion.com/tui/status-bar): Powerline-style status bar
- [Footer](https://docs.connectonion.com/tui/footer): Help tips footer
- [Divider](https://docs.connectonion.com/tui/divider): Visual separator
- [Fuzzy Matching](https://docs.connectonion.com/tui/fuzzy): Fuzzy search scoring
- [Keyboard Input](https://docs.connectonion.com/tui/keys): Raw keyboard input handling
- [Providers](https://docs.connectonion.com/tui/providers): Data source providers for autocomplete
- [Chat Interface](https://docs.connectonion.com/tui/chat): Terminal chat UI

## Debug

- [Interactive Debugging](https://docs.connectonion.com/auto-debug): Debug agents with auto_debug() and breakpoints
- [Auto Debug Exception](https://docs.connectonion.com/auto-debug-exception): AI-powered crash analysis
- [Browser Screenshots](https://docs.connectonion.com/tools/browser): Capture and debug browser state
- [Logging](https://docs.connectonion.com/logging): Automatic activity logging to .co/logs/
- [@xray Decorator](https://docs.connectonion.com/xray): Runtime context injection for debugging
- [trace() Visual Flow](https://docs.connectonion.com/xray/trace): Visualize agent execution flow

## Examples

- [All Examples](https://docs.connectonion.com/examples): Browse all example agents
- [Calculator](https://docs.connectonion.com/examples/calculator): Simple calculator agent
- [Browser Automation](https://docs.connectonion.com/examples/browser): Web automation agent

## Blog — Design Decisions

- [Complete engineering blog index](https://docs.connectonion.com/blog/llms.txt): AI-readable catalog of every published field note, with canonical URLs, summaries, and topics
- [Engineering blog RSS](https://docs.connectonion.com/blog/feed.xml): Chronological feed of new ConnectOnion design decisions and implementation lessons

- [An ID Before a Session](https://docs.connectonion.com/blog/an-id-before-a-session): Why a Claude SessionStart ID may not yet be resumable, and how the first OIP browser turn starts safely

- [The Approval the Browser Could Not See](https://docs.connectonion.com/blog/the-approval-the-browser-could-not-see): Claude Station's OIP approval lifecycle, real Haiku browser evidence, and remaining permission limits

- [Headless Does Not Mean Unconfigured](https://docs.connectonion.com/blog/headless-does-not-mean-unconfigured): Unattended Auto honors deliberate browser/status grants without turning the historical broad co wildcard into unlimited authority
- [An Image Prefix Is Not an Image](https://docs.connectonion.com/blog/an-image-prefix-is-not-an-image): Strict completeness checks keep truncated data URLs and base64-looking text out of the image upload path
- [A Patch Must Move Forward](https://docs.connectonion.com/blog/a-patch-must-move-forward): Stable patches require a tracked forward-port into every active higher line, and open obligations block newer preview, RC, and next-minor releases
- [The Page That Could Only Grow](https://docs.connectonion.com/blog/the-page-that-could-only-grow): co rem 1.9.2b1 lets each investigation pass delete as well as add, so pages improve instead of only growing
- [A First Run That Investigates](https://docs.connectonion.com/blog/a-first-run-that-investigates): co rem 1.9.1's first run investigates each person over several passes, edits pages in place and deepens people with older mail
- [A First Run Must Finish Its Map](https://docs.connectonion.com/blog/a-first-run-must-finish-its-map): Why co rem's first run investigates every eligible mapped page, shows progress, and keeps model and nightly failures visible
- [Your Servers, Your Regions, Your Shared Mailboxes](https://docs.connectonion.com/blog/connectonion-1-6-12): ConnectOnion 1.6.12 behavior and the rule that applicable stable fixes move into every supported newer release line without copying old version metadata
- [The Work Room Is a Client, Not a Status Panel](https://docs.connectonion.com/blog/workroom-is-a-view): Remote Codex and Claude Code conversation, lifecycle, permissions, and fixed provider input inside one OIP client shell
- [One Browser Protocol, Native Coding Adapters](https://docs.connectonion.com/blog/oip-native-coding-adapters): OIP browser ownership, native Codex and Claude Code adapter boundaries, deterministic Codex routing, and open-without-turn Work Rooms
- [The Owner Needs a Door](https://docs.connectonion.com/blog/the-owner-needs-a-door): Secure first-owner onboarding, one-time invite creation, masked inspection, and deliberate secret reveal
- [A Page Should Not Become a Wall](https://docs.connectonion.com/blog/a-page-should-not-become-a-wall): Traversable mailbox limits, deterministic pagination, and exact next-page CLI guidance
- [Why input() Over run()](https://docs.connectonion.com/blog/input-method): API naming design decision
- [Why llm_do() Over llm()](https://docs.connectonion.com/blog/llm-do): LLM function naming rationale
- [Why We Chose "Trust"](https://docs.connectonion.com/blog/trust-keyword): Trust keyword design decision
- [Network Protocol Design](https://docs.connectonion.com/blog/network-protocol-design): Architecture decisions
- [co ai Delegates to Codex and Claude Code](https://docs.connectonion.com/blog/connectonion-1-7): ConnectOnion 1.7.0 stable — live resumable Work Room, read-only/auto/full-access permission modes, intent-led tool activity
- [What Makes an Agent 10x](https://docs.connectonion.com/blog/what-makes-an-agent-10x): Vision essay — verifiable work, life in time, sedimenting experience, bounded delegation, real-world reach
- [ConnectOnion 1.6.0 Release](https://docs.connectonion.com/blog/connectonion-1-6): Safer remote agents and a cleaner credential boundary
- [Changing the Default Model Is a Backend Decision First](https://docs.connectonion.com/blog/gemini-37-default): ConnectOnion 1.6.6 — Gemini 3.7 Flash default and release ordering
- [The Agent That Was Itself, and Billed Someone Else](https://docs.connectonion.com/blog/deployed-agent-identity): Deployed agent identity and billing attribution (1.6.5)
- [An Approval Is Not Execution Time](https://docs.connectonion.com/blog/an-approval-is-not-execution-time): Tool-approval lifetime vs execution — permission scoping for native coding turns
- [A Work Room Is a Summary, Not a Transcript](https://docs.connectonion.com/blog/a-work-room-is-a-summary-not-a-transcript): The finite OIP envelope for native coding activity
- [Agent Address Format](https://docs.connectonion.com/blog/agent-address-format): Ed25519 public key addressing
- [Why "Address" Over "Identity"](https://docs.connectonion.com/blog/naming-is-hard): Terminology choice
- [Progressive Disclosure CLI](https://docs.connectonion.com/blog/cli-ux-progressive-disclosure): CLI UX design
- [Auto-Debug Design Evolution](https://docs.connectonion.com/blog/auto-debug-evolution): Debug feature iteration

## Links

- [GitHub](https://github.com/openonion/connectonion): Source code and issues
- [PyPI](https://pypi.org/project/connectonion/): Python package
- [Discord](https://discord.gg/4xfD9k8AUF): Community chat
- [Release Channels](https://docs.connectonion.com/releases): Stable, stabilizing, and opt-in preview versions with exact installation commands
- [Roadmap](https://docs.connectonion.com/roadmap): Upcoming features

## Unreleased candidate
- [1.8.4 candidate guide](https://docs.connectonion.com/candidates/1.8.4/README.md): implementation under review, migration and contracts; no published package pin.