# Wall-E + CTM

**Wall-E** is your personal digital twin — an AI agent that learns from your Slack, email, and calendar to build a searchable second brain, answer questions in your voice, and automate daily workflows.

**CTM** (Coding Task Manager) is an agent task manager and terminal multiplexer — a web dashboard for running Claude Code, Codex, Gemini, Aider, OpenCode, Cursor Agent, and other AI coding sessions, plus prompts, code review, phone access, and Wall-E control.

Together they give you a local-first AI command center: a browser-based workspace where you manage AI coding sessions, chat with an AI that knows your work context, respond from your phone, and automate the repetitive parts of your day.

## What You Get

### CTM — Agent Task Manager
- **Terminal multiplexer** — run multiple AI coding agents side-by-side in browser tabs, with session history, search, and replay
- **Prompt library** — rich-text editor with versioning, folders, tags, and one-click send to any active session
- **Prompt queue** — batch multiple prompts and send them sequentially to a session with idle detection
- **Shadow Approver** — learns your permission patterns and auto-approves safe operations across sessions
- **Code review** — AI-assisted diff review across projects with inline comments
- **Phone access** — pair a phone with a QR code and use the mobile CTM UI through Microsoft Dev Tunnels, Tailscale, Cloudflare Tunnel, or Walle Remote
- **Session insights** — AI analysis of your coding-agent usage with actionable recommendations
- **Permission manager** — fine-grained control over what coding agents can do automatically, with risk tiers and rule consolidation

### Wall-E — Personal AI Agent
- **Second brain** — ingests Slack messages, calendar events, and sent emails into a local SQLite database with full-text search
- **Chat** — ask questions about your work, meetings, and conversations — grounded in your actual data with citations
- **Scheduled skills** — morning briefings, Slack sync, calendar sync, email digest, and custom skills on configurable schedules
- **Background tasks** — recurring or one-shot tasks with live logs, skill execution, and checkpoint/resume
- **Knowledge graph** — automatically extracts facts, relationships, and patterns from your data over time
- **People intelligence** — tracks relationships, communication patterns, trust levels, and personas
- **MCP integration** — calls tools on Slack, GitHub, and custom MCP servers directly from chat
- **macOS native** — calendar via EventKit, email via AppleScript, Spotlight file search, desktop notifications, clipboard access

## Architecture

```
CTM (port 3456)                    Wall-E Daemon
+-----------------------+          +------------------------+
| Web Dashboard         |          | Agent Daemon           |
|  - Sessions (pty)     |  <--->   |  - Ingest loop (60s)   |
|  - Prompts editor     |          |  - Think loop (120s)   |
|  - Prompt queue       |          |  - Reflect loop (1hr)  |
|  - Shadow Approver    |          |  - Skills loop (5min)  |
|  - Code review        |          |  - Tasks loop (30s)    |
|  - Session insights   |          |                        |
|  - Permission manager |          | Chat Engine            |
|  - Wall-E chat tab    |          |  - Tool use (local+MCP)|
+-----------------------+          |  - Memory search       |
         |                         |  - Skill execution     |
         v                         +------------------------+
   task-manager.db                          |
   (sessions, prompts,                      v
    rules, reviews)              wall-e-brain.db
                                 (memories, knowledge,
                                  people, skills, tasks)
```

## Quickstart

```bash
npx create-walle install ./walle
```

Open **http://localhost:3456** — the setup page walks you through adding your API key, connecting integrations, and pairing your phone if you want mobile access. Your name and timezone are auto-detected.

Or clone manually:

```bash
git clone <repo-url> walle && cd walle
cd claude-task-manager && npm install && cd ..
cd wall-e && npm install && cd ..
node claude-task-manager/server.js
```

The first run auto-creates `.env`, `wall-e-config.json`, and `~/.walle/data/`. Finish setup at http://localhost:3456/setup.html.

## Dashboard Features

### Sessions
Terminal multiplexer for AI coding agents — create, monitor, and manage multiple sessions from a single browser tab. Features include:
- Live terminal output via WebSocket (xterm.js)
- Session search and AI-powered search across all session history
- AI auto-titling for sessions
- Project grouping and filtering
- Copy session command (with working directory)
- Session replay and review

### Prompts
Rich-text prompt editor with a full formatting toolbar. Organize prompts into folders, tag them, track usage across sessions, and send to any active coding-agent session with one click.
- **Composite prompts** — parent prompt with sub-prompts that compose into a single message
- **Prompt queue** — batch multiple prompts, send sequentially with idle detection between items
- **Power tools** — chains (multi-step sequences), templates, pattern detection, harvest (extract prompts from session history), and AI copilot suggestions
- **Usage tracking** — see which sessions used which prompts and how often

### Wall-E Chat
Chat directly with Wall-E from the dashboard. Wall-E has access to your full brain (memories, knowledge, people) and can:
- Search your Slack messages, emails, and calendar
- Run skills on demand (morning briefing, Slack sync, etc.)
- Call MCP tools (Slack, GitHub, etc.)
- Create and manage background tasks
- Execute shell commands, read files, take screenshots
- Answer questions grounded in your actual data

Sub-tabs: Chat, Tasks (background task manager), Skills (view and run), Brain (knowledge graph), Actions, Timeline, Questions, Status.

### Phone Access
Pair a phone from Setup and open the mobile CTM UI at `/m/`. CTM supports Microsoft Dev Tunnels, Tailscale, Cloudflare Tunnel, and Walle Remote paths so you can monitor sessions and respond while away from the desktop browser.

### Shadow Approver
Learns your permission patterns from coding-agent sessions and auto-approves safe operations. Features:
- Pattern learning from your approval history
- AI-driven approval decisions with confidence scoring
- Domain-specific trust tiers (Observe, Draft, Guarded, Autonomous)
- Rule consolidation (merges similar Bash rules)
- Decision history and audit trail

### Code Review
AI-assisted code review across projects:
- Inline diff viewer
- Multi-project support
- AI review comments with confidence levels
- Send review to a coding-agent session for implementation

### Session Insights
AI analysis of your coding-agent usage patterns:
- Workflow recommendations (automate repetitive tasks)
- Prompt effectiveness analysis
- Skill gap detection
- Cost-saving suggestions
- Session statistics

### Permission Manager
Fine-grained control over what coding agents can do automatically:
- Search and filter across all rules
- Risk-based categorization (LOW, MEDIUM, HIGH)
- Per-project or global scope
- Rule consolidation for similar patterns
- Import/export with Claude Code's settings files

## Configuration

All configuration lives in `.env` (auto-generated on first run). Edit directly or use the browser setup page.

### API Authentication

Wall-E supports three ways to connect to Claude:

**Option A: Direct Anthropic API key**
```env
ANTHROPIC_API_KEY=sk-ant-...
```

**Option B: Portkey / API gateway**
```env
ANTHROPIC_BASE_URL=https://your-gateway.example.com/v1
ANTHROPIC_AUTH_TOKEN=sk-ant-api03-unused
ANTHROPIC_CUSTOM_HEADERS_B64=<base64-encoded headers>
```

**Option C: Corporate devbox (auto-detected)**
If you use `devbox ai -c claude`, Wall-E auto-reads your gateway credentials from `~/.devbox/secrets/claude/auth_headers` — no config needed.

### Environment Variables

| Variable | Required | Description |
|---|---|---|
| `ANTHROPIC_API_KEY` | Yes* | Anthropic API key or Portkey key |
| `ANTHROPIC_BASE_URL` | No | API gateway URL (for Portkey, corporate proxies) |
| `ANTHROPIC_AUTH_TOKEN` | No | Auth token when using a gateway |
| `ANTHROPIC_CUSTOM_HEADERS_B64` | No | Base64-encoded custom headers (Portkey virtual keys, metadata) |
| `WALLE_OWNER_NAME` | Auto | Your name (auto-detected from `git config`) |
| `WALLE_MODEL` | Auto | Model selection (probed on setup: claude-sonnet-4-6, haiku-4-5, etc.) |
| `CTM_PORT` | No | Dashboard port (default: `3456`) |
| `WALL_E_PORT` | No | Wall-E API port (default: `CTM_PORT + 1`) |
| `WALL_E_DATA_DIR` | No | Data directory (default: `~/.walle/data`) |
| `CTM_DATA_DIR` | No | CTM data directory (default: `~/.walle/data`) |
| `SLACK_TOKEN` | No | Slack token (set via OAuth — click "Connect" in setup) |
| `SLACK_OWNER_USER_ID` | No | Your Slack user ID |
| `SLACK_OWNER_HANDLE` | No | Your Slack handle |

*Not required if using a gateway (`ANTHROPIC_BASE_URL`) or devbox auto-detection.

## Bundled Skills

Wall-E ships with skills that run on a schedule to keep your brain up to date:

| Skill | Schedule | Description |
|---|---|---|
| `google-calendar` | every 30m | Syncs macOS Calendar events (Google, iCloud, Outlook) via EventKit |
| `slack-sync` | every 15m | Incremental Slack message sync via MCP |
| `slack-backfill` | manual | Full Slack history backfill (2022-present) |
| `email-sync` | every 30m | Syncs sent emails from macOS Mail via JXA |
| `email-digest` | daily 7am | Summarizes recent email activity |
| `morning-briefing` | daily 7am | AI-generated daily briefing: calendar, Slack activity, tasks, questions |
| `memory-search` | on-demand | Full-text search across all memories |
| `file-ingest` | manual | Read a folder of files into the brain with glob filtering |

### Creating Custom Skills

Skills are defined as `SKILL.md` files with YAML frontmatter:

```yaml
---
name: my-skill
description: What this skill does
version: 1.0.0
execution: script        # or "agent" for LLM-driven skills
entry: run.js
trigger:
  type: interval
  schedule: "every 30m"
tags: [sync, data]
---
```

Place skills in `wall-e/skills/_bundled/your-skill/SKILL.md` or load from a custom directory.

## Integrations

| Integration | How it works | Setup |
|---|---|---|
| **Slack** | OAuth + MCP protocol for search, read, send | Click "Connect" in setup page |
| **Google Calendar** | macOS EventKit (reads all calendars: Google, iCloud, Outlook) | Automatic on macOS |
| **Email** | macOS Mail via JXA/AppleScript | Automatic on macOS |
| **GitHub** | MCP server (if configured in Claude Code) | Via MCP config |
| **Custom MCP servers** | Any MCP-compatible server | Add to MCP config |

## API

CTM runs on port 3456. Key endpoints:

| Method | Path | Description |
|---|---|---|
| GET | `/api/services/status` | CTM and Wall-E process status |
| POST | `/api/restart/ctm` | Restart CTM server |
| POST | `/api/restart/walle` | Restart Wall-E daemon |
| POST | `/api/start/walle` | Start Wall-E daemon |
| POST | `/api/stop/walle` | Stop Wall-E daemon |
| GET | `/api/wall-e/status` | Brain stats, loop health, owner info |
| GET | `/api/wall-e/memories` | List memories (filterable by source, since, limit) |
| GET | `/api/wall-e/knowledge` | List knowledge entries |
| GET | `/api/wall-e/people` | List known people |
| GET | `/api/wall-e/timeline` | Memory timeline |
| GET | `/api/wall-e/tasks` | List background tasks |
| POST | `/api/wall-e/chat` | Chat with Wall-E (supports SSE streaming) |
| GET | `/api/prompts` | List prompts |
| GET | `/api/recent-sessions` | List recent coding-agent sessions |

## Tech Stack

- **Runtime**: Node.js (no framework — raw `http.createServer`)
- **Database**: SQLite via better-sqlite3 (WAL mode, FTS5 full-text search)
- **AI**: Claude API via Anthropic SDK (supports Portkey gateway)
- **Frontend**: Vanilla HTML/CSS/JS (no build step, no React)
- **Terminal**: xterm.js (frontend) + node-pty (backend)
- **macOS integration**: EventKit (calendar), JXA (email/AppleScript), Spotlight (file search)

## Development

```bash
# Start dev instance (doesn't affect primary on :3456)
bash bin/dev.sh

# Run Wall-E tests
cd wall-e && npm test

# Run Slack backfill manually
node scripts/slack-backfill.js 2024-01  # single month
node scripts/slack-backfill.js incremental  # new messages only

# Run calendar sync manually
node skills/_bundled/google-calendar/run.js

# Run morning briefing manually
node skills/_bundled/morning-briefing/run.js
```

## License

MIT
