# NeuralClaw

NeuralClaw is a Python agent framework built around a five-cortex runtime:
Perception, Memory, Reasoning, Action, and Evolution. The current repository
state now covers the full `AGENT.md` roadmap, including vector memory,
persistent identity modeling, browser and desktop control, streaming,
structured output, observability, output filtering, audit replay, workspace
integrations, and A2A-compatible federation.

## Current Capabilities

- **Computer use**: Take screenshots, analyze screen content with vision,
  click UI elements, type text, press hotkeys, and launch apps — all
  controllable remotely via Telegram, Discord, or any channel
- **Dynamic self-awareness**: Agent knows its own capabilities and active
  tools; never says "I can't" when it has a tool for the job
- **Multi-provider routing**: `openai` (GPT-5.4), `anthropic` (Claude 4.6),
  `openrouter`, `proxy`, `local` (Ollama) — with GPT-5/o-series API compat
- managed browser-session providers: `chatgpt_app`, `claude_app`
- token-backed session auth: `chatgpt_token`, `claude_token`
- episodic, semantic, procedural, vector, and identity memory with smart
  importance scoring
- fast-path, deliberative, reflective, structured, and meta-cognitive reasoning
- vision perception, browser automation, and desktop automation
- streaming responses and Discord voice playback
- Google Workspace and Microsoft 365 built-in skills
- traceline observability, Prompt Armor v2, and audit replay
- swarm, native federation, and A2A interoperability

## Install

```bash
# Core package
pip install neuralclaw

# Local checkout
pip install -e .

# Development
pip install -e ".[dev]"

# Optional extras
pip install -e ".[voice]"
pip install -e ".[browser]"
pip install -e ".[desktop]"
pip install -e ".[google]"
pip install -e ".[microsoft]"
pip install -e ".[vector]"

# Everything
pip install -e ".[all,dev]"
```

External runtimes still required for some integrations:

- Playwright browser binaries
- Node.js for the WhatsApp bridge
- `signal-cli` for Signal
- FFmpeg for Discord voice playback

```bash
python -m playwright install chromium
```

## Quick Start

```bash
neuralclaw init

neuralclaw session setup chatgpt
neuralclaw session setup claude

neuralclaw session auth chatgpt
neuralclaw session auth claude
neuralclaw session auth google
neuralclaw session auth microsoft

neuralclaw local setup
neuralclaw channels setup

neuralclaw status
neuralclaw session status
neuralclaw doctor

neuralclaw chat
neuralclaw gateway
```

## Providers

| Provider | Purpose | Setup |
|---|---|---|
| `openai` | official OpenAI API | `neuralclaw init` |
| `anthropic` | official Anthropic API | `neuralclaw init` |
| `openrouter` | OpenRouter relay | `neuralclaw init` |
| `proxy` | OpenAI-compatible proxy | `neuralclaw proxy setup` |
| `local` | Ollama or compatible local endpoint | `neuralclaw local setup` |
| `chatgpt_app` | managed ChatGPT browser session | `neuralclaw session setup chatgpt` |
| `claude_app` | managed Claude browser session | `neuralclaw session setup claude` |
| `chatgpt_token` | direct ChatGPT token access | `neuralclaw session auth chatgpt` |
| `claude_token` | direct Claude token access | `neuralclaw session auth claude` |

## Channel Trust

Each route can run in one of three modes:

| Mode | Behavior |
|---|---|
| `open` | always accept inbound messages |
| `pair` | require one-time `/pair` for that route |
| `bound` | only trusted bindings may talk |

Discord also supports streamed text edits and optional voice playback.

## Project Layout

```text
neuralclaw/
  bus/         event bus and telemetry
  channels/    Telegram, Discord, Slack, Signal, WhatsApp, Web, trust layer
  cortex/      perception, memory, reasoning, action, evolution, observability
  providers/   API providers, session providers, router
  session/     managed browser-session runtime
  skills/      manifest model, registry, built-ins
  swarm/       delegation, consensus, mesh, federation
  gateway.py   orchestration entrypoint
  cli.py       command-line interface
  config.py    config, keychain helpers, validation
```

## Docs

- [docs/README.md](docs/README.md)
- [docs/configuration.md](docs/configuration.md)
- [docs/architecture.md](docs/architecture.md)
- [docs/security.md](docs/security.md)
- [docs/federation.md](docs/federation.md)

## Verification

```bash
pytest -q
python -m compileall neuralclaw
python -m build
```
