# 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
- **SkillForge**: Proactive skill synthesis — give it a URL, API spec, Python
  library, GitHub repo, MCP server, or plain description and it generates
  domain-specific tools tailored to your use case. Works from any channel
  (`/forge`, `!forge`, `forge:`) or the agent forges its own skills mid-conversation
- **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

## SkillForge — Teach Your Agent New Tricks

SkillForge turns any input into a deployable NeuralClaw skill. No developer needed.

```bash
# CLI
neuralclaw forge create "https://api.stripe.com" --use-case "charge chiro patients"
neuralclaw forge create "twilio" --use-case "send appointment reminders"
neuralclaw forge create "I want to look up drug interactions"

# From Telegram
/forge https://github.com/owner/repo for: analyze X-ray reports

# From Discord
!forge twilio --for send SMS reminders

# The agent can forge its own skills mid-conversation
User: "Can you learn to query our Google Sheets?"
Agent: [forges sheets_query skill] → "Done, I can now read your reports directly."
```

Supported sources: URLs, OpenAPI/Swagger specs, GraphQL endpoints, Python libraries,
GitHub repos, MCP servers, code files, or natural language descriptions.

Skills are saved to `~/.neuralclaw/skills/` and hot-loaded without restart.

## 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
```
