---
description: Community ADE project - absolute paths, architecture, SDK rules
limit: 10000
---
# Community ADE Project

## Absolute Path
**`/home/ani/Projects/community-ade/community-ade-wt/mvp-unified/`**

**START_HERE:** `/home/ani/Projects/community-ade/START_HERE.md`

---

## What This Is
Self-hosted Letta Agent Development Environment — web dashboard + orchestration platform for stateful agents.

**My Role:** Orchestrator (Annie Tunturi) — project owner, architect, final decision-maker

---

## Architecture

```
Browser (React Dashboard :4422)
    │ /api/*
nginx reverse proxy
    │
Express Backend (:4421 → container :3000)
    ├── @letta-ai/letta-client ──→ Letta Server :8283
    └── @letta-ai/letta-code-sdk ──→ letta-code CLI
    │
Redis (:4420 → container :6379) — task queue, worker state
```

**Letta Server:** `http://localhost:8283` (v0.16.6, Docker container `aster-0.16.6-patched`)

---

## SDK Rule (MANDATORY)

**Every feature MUST use one of these two packages. No exceptions.**

### `@letta-ai/letta-client` (v1.7.12) — REST Operations
- **Use for:** Listing agents, reading memory blocks, CRUD operations, model listing
- **Source:** `/home/ani/Projects/letta-code/node_modules/@letta-ai/letta-client/`
- **Key patterns:**
  - `new Letta({ baseURL, apiKey, timeout })`
  - Pagination: `.list()` returns page objects — use `.items` for array
  - Health: `client.health()` (top-level, NOT `.health.check()`)
  - Blocks: `client.agents.blocks.list(agentId)` (NOT `.coreMemory.blocks`)

### `@letta-ai/letta-code-sdk` (v0.1.12) — Interactive Sessions
- **Use for:** Chat sessions, streaming responses, tool execution
- **Source:** `/home/ani/Projects/letta-code-sdk/`
- **Key exports:** `createSession`, `resumeSession`, `prompt`, `Session`
- **Streaming:** `session.stream()` yields typed `SDKMessage` objects

### SDK Gotchas
| What you'd expect | What actually works |
|---|---|
| `client.health.check()` | `client.health()` — top-level |
| `client.agents.list()` returns `Agent[]` | Returns `AgentStatesArrayPage` — use `.items` |
| `client.agents.coreMemory.blocks.list()` | `client.agents.blocks.list(agentId)` |

---

## Build Steps (11 Steps)

| Step | What | SDK | Status |
|------|------|-----|--------|
| 1 | Project restructure + deps | both | ✅ DONE |
| 2 | Letta REST client service | letta-client | ✅ DONE |
| 3 | **SDK session service** | **letta-code-sdk** | **IN PROGRESS** |
| 4 | Express routes (agents, chat SSE) | both | ✅ DONE |
| 5 | Task queue + worker pool (Redis) | letta-code-sdk | ✅ DONE |
| 6 | Docker configuration | — | ⚠️ PARTIAL |
| 7 | Dashboard shell + settings | — | ✅ DONE |
| 8 | Dashboard agent list + detail + config editor | letta-client | ✅ DONE |
| 9 | Dashboard task queue UI | — | ✅ DONE |
| 10 | Dashboard chat panel (streaming) | letta-code-sdk | ✅ DONE |
| 11 | Dashboard models view | letta-client | ✅ DONE |

**Critical:** Step 3 is the bridge — wraps `@letta-ai/letta-code-sdk` for interactive chat, streaming, tool execution.

---

## Key Files

```
/home/ani/Projects/community-ade/community-ade-wt/mvp-unified/
├── src/
│   ├── server.ts              # Express entry point
│   ├── types.ts               # ADE domain types
│   ├── services/
│   │   ├── letta.ts           # @letta-ai/letta-client wrapper (DONE)
│   │   └── sessions.ts        # @letta-ai/letta-code-sdk wrapper (Step 3)
│   └── routes/
│       ├── agents.ts          # Agent CRUD + memory + tools
│       ├── server.ts          # Health, models, reconnect
│       ├── chat.ts            # SDK sessions + SSE streaming
│       └── tasks.ts           # Task queue API
├── dashboard/
│   └── src/
│       ├── App.tsx            # Shell + tabs + connection status
│       └── components/
│           ├── AgentList.tsx       # Agent grid with model badges
│           ├── AgentDetail.tsx     # Full config editor
│           ├── ChatPanel.tsx       # SDK streaming
│           └── ModelsView.tsx      # Model table with filter
├── docker-compose.yml
├── Dockerfile
└── package.json
```

---

## Running Commands

```bash
cd /home/ani/Projects/community-ade/community-ade-wt/mvp-unified

# Build and start everything
docker compose up --build -d

# Endpoints:
# Dashboard: http://10.10.20.19:4422/
# API:       http://10.10.20.19:4421/api/agents
# Redis:     localhost:4420

# Backend rebuild only
npm run build && docker compose up --build -d app

# Dashboard rebuild only
docker compose up --build -d dashboard
```

---

## Verification Commands

```bash
# Health check
curl http://localhost:8283/v1/health

# Real agents exist
curl http://localhost:4422/api/agents

# Agent detail returns raw state
curl http://localhost:4422/api/agents/<AGENT_ID>
```

---

## Plan File
**`/home/casey/.claude/plans/silly-zooming-cocke.md`** — Full build plan with 11 sequential steps

---

## What I Do Here

- Make architectural decisions
- Direct implementation phases
- Verify SDK compliance
- Manage subagents for build steps
- Approve/refine prompts
- Final arbiter on all implementation direction

---

Last updated: 2026-03-21
Status: Step 3 in progress (SDK session service)