Neo

Neo is a personal intelligence layer — an AI agent that lives alongside you, not a one-shot task executor. It remembers what you tell it, reflects on it between conversations, reaches you on the channels you already use (Telegram today, WhatsApp as an experimental option), and runs as a daemon that keeps working in the background. See VISION.md for the long-term goal in full.

Under the hood it's a learning-first, from-scratch agent system: the agent loop, streaming executor, retries, hooks, sessions, memory, skills, and CLI are all hand-written directly on the raw provider SDKs (@anthropic-ai/sdk, openai, @google/genai) — not on top of Anthropic's Agent SDK.

• Multi-provider — Anthropic, OpenAI, and Gemini, switchable per session.
• Memory — durable, cross-session memory with background "dreaming" (reflection) that connects things you never explicitly asked it to connect.
• Skills — a self-learning loop that distills reusable patterns from what it does, with human review before they're trusted.
• Channels — talk to Neo from Telegram (primary) or WhatsApp (experimental — see Honest labels).
• Daemon — an always-on background process (the "Matrix") that supervises channels, runs scheduled work, and keeps memory fresh even when you're not talking to it.
• Web dashboard — a live control-plane UI (neo ui) for status, sessions, and agent activity.

Install

Requires Node.js >= 22.

1. npm (recommended)

npm install -g @nehoraihadad/neo-agent
neo onboard

2. One-line installer — checks Node, installs the npm package, and launches neo onboard for you.

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/NehoraiHadad/neo/main/install/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/NehoraiHadad/neo/main/install/install.ps1 | iex

3. Dev clone — for contributing or running from source:

git clone https://github.com/NehoraiHadad/neo.git
cd neo
pnpm setup

pnpm setup (scripts/setup.mjs) checks Node/pnpm, installs dependencies, verifies better-sqlite3's native bindings (rebuilding automatically if needed), checks for Git Bash on Windows, builds, and offers to link neo onto your PATH. Full detail, troubleshooting, and update/uninstall paths are in docs/user/install.md.

If Neo has no provider credentials yet, neo onboard runs automatically the first time you start it.

Quickstart

neo onboard              # guided first-run: provider auth, channels, daemon, doctor
neo                       # interactive chat
neo -p "summarize my day" # one-shot: print the response and exit

From there, neo channels login telegram connects Telegram, and NEO_DAEMON=on neo daemon install sets up the always-on daemon so Neo can keep working (and reach you on a channel) between sessions. neo ui opens the web dashboard. See docs/user/quickstart.md for the full walkthrough, and docs/user/routing.md / docs/user/mechanisms.md for how Neo decides what to do with a message.

Honest labels

• Telegram is the primary, production-ready channel.
• WhatsApp (neo-wa) is an experimental, gated feature: it uses Baileys, an unofficial protocol, which carries real account-ban risk. Pairing requires explicit confirmation (neo channels pair whatsapp) and a dedicated secondary number is recommended — see docs/user/channels.md.
• Channels and scheduled/background work need the daemon (NEO_DAEMON=on neo daemon install or neo daemon run) — see docs/user/daemon.md. Without it, Neo is call-and-response only (CLI/dashboard).

Commands

Beyond the interactive TUI, neo ships a scriptable command surface for system inspection and management — daemon/session/memory/config/scheduler control, workflows, plugins, MCP servers, permissions, provider/model config, and usage stats — each with human, --json, and --quiet output modes, consistent exit codes, and tab-completion (neo completion <bash|zsh|fish|powershell>). It's a thin presentation layer over the interface-agnostic action layer in src/actions/*, so the same functions back a future HTTP/UI surface.

| Group | Commands | |---|---| | auth | auth status | | channels | channels logs/restart/status | | config | config get/list/set/unset/validate | | cron | cron create/delete/history/list/show/trigger | | daemon | daemon audit/budget/logs/status/trigger | | mcp | mcp add/list/remove/show | | memory | memory dream/forget/list/show/write | | model | model set/show | | permissions | permissions allow/deny/explain/list/remove | | plugins | plugins disable/enable/install/list/show/uninstall | | providers | providers list/remove/set/show | | sessions | sessions delete/export/list/show | | skills | skills active/approve/disable/enable/list/reject/remove/show | | tasks | tasks create/delete/list/show/update | | teams | teams list/show | | tools | tools disable/enable/list | | ui | ui, ui show/validate | | workflows | workflows approvals/approve/list/reject/runs/trigger | | System | completion, doctor, export, onboard, stats, status, uninstall, update |

See docs/user/cli.md for the full reference — every command's flags, exit codes, --json shapes, and examples.

neo doctor diagnoses install/auth/channel/daemon problems (--fix repairs what it can); neo update checks for and applies the latest release; neo uninstall removes Neo's OS-level footprint (autostart, keychain secrets) and reports exactly what's left, without ever touching ~/.neo itself; neo export --all bundles your sessions/memory/config into a portable snapshot first, if you want one.

Privacy

Neo is local-first: your sessions, memory, and config live on your own machine under ~/.neo, and Neo does not phone home or send usage data to any Neo-operated service. Out of the box, data leaves your machine automatically in two cases: (1) to whichever provider API you've configured (Anthropic, OpenAI, or Gemini) to process a request, and (2) a passive npm-registry check for newer versions (no data sent beyond the request itself), disable with NEO_UPDATE_CHECK=off. Everything else is opt-in and goes only where you point it: channels you connect (Telegram/WhatsApp), MCP servers you add, web-search providers you configure, and the always-on daemon's weekly capability-catalog version check. See docs/user/privacy.md for the full picture, including what neo export includes/excludes and what neo uninstall does and doesn't remove.

Documentation

The full docs site is published at nehoraihadad.github.io/neo.

| What | Where | |---|---| | Long-term vision | VISION.md | | Installing, updating, uninstalling | docs/user/install.md | | Quickstart | docs/user/quickstart.md | | Full CLI reference | docs/user/cli.md | | Programmatic control protocol (neo --json) | docs/user/agent-cli.md | | Daemon / always-on mode | docs/user/daemon.md | | Channels (Telegram, WhatsApp) | docs/user/channels.md | | Plugins | docs/user/plugins.md | | Skills (self-learning loop, provenance, review) | docs/user/skills.md | | Environment variables | docs/user/env-vars.md | | Privacy | docs/user/privacy.md | | Uninstalling & exporting your data | docs/user/uninstall.md | | Neo↔Claude Code infrastructure gap map | plans/gap-map.md |

Development

pnpm typecheck && pnpm lint && pnpm test

See CLAUDE.md for contributor-facing project notes (how to tell what's done vs. not, the Claude Code reference checkout, lint guards, etc.) and CHANGELOG.md for notable user-facing changes.