this repo has no description
docs: add comprehensive development setup guide
Updates README.md with complete setup instructions:
- Architecture overview
- Prerequisites list
- Step-by-step dev environment setup
- Environment variables reference (required vs optional)
- Telegram bot setup via BotFather
- Webhook vs polling mode explanation
- Docker services management commands
- Testing instructions
- Project structure overview
- Milestone progress tracker
- Troubleshooting section
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+214
-5
+214
-5
README.md
+214
-5
README.md
···
1
-
# assistant
1
+
# ADHD Support Agent
2
+
3
+
A Telegram bot that helps with ADHD task management, brain dumps, and gentle accountability. Built with Bun, Letta, and Claude.
2
4
3
-
To install dependencies:
5
+
## Architecture
6
+
7
+
```
8
+
Telegram → Bun Adapter → Letta Agent → Anthropic (via proxy)
9
+
```
10
+
11
+
- **Bun**: Runtime and HTTP server
12
+
- **Letta**: AI agent framework with persistent memory
13
+
- **anthropic-proxy**: OAuth proxy for Anthropic API access
14
+
- **SQLite**: Local storage for items, wins, and context
15
+
16
+
## Prerequisites
17
+
18
+
- [Bun](https://bun.sh) v1.1+
19
+
- [Docker](https://docs.docker.com/get-docker/) and Docker Compose
20
+
- Telegram account (for bot setup)
21
+
- OpenAI API key (for embeddings)
22
+
- Anthropic account (for Claude access via OAuth)
23
+
24
+
## Development Setup
25
+
26
+
### 1. Install dependencies
4
27
5
28
```bash
6
29
bun install
7
30
```
8
31
9
-
To run:
32
+
### 2. Configure environment
33
+
34
+
```bash
35
+
cp .env.example .env
36
+
```
37
+
38
+
Edit `.env` with your values (see sections below for how to get each).
39
+
40
+
### 3. Start Docker services
41
+
42
+
Start the anthropic-proxy and Letta services:
43
+
44
+
```bash
45
+
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d
46
+
```
47
+
48
+
This starts:
49
+
- `anthropic-proxy` on port 4001
50
+
- `letta` on port 8283
51
+
52
+
The dev override (`docker-compose.dev.yml`) excludes the app service so you can run it locally.
53
+
54
+
### 4. Complete Anthropic OAuth
55
+
56
+
The anthropic-proxy requires OAuth setup for Anthropic API access:
57
+
58
+
1. Open http://localhost:4001 in your browser
59
+
2. Complete the Anthropic OAuth flow
60
+
3. Copy the session ID from the callback
61
+
4. Add it to your `.env`:
62
+
```
63
+
ANTHROPIC_PROXY_SESSION_ID=your_session_id_here
64
+
```
65
+
66
+
### 5. Run the app
67
+
68
+
```bash
69
+
bun run src/index.ts
70
+
```
71
+
72
+
Or with hot reload:
73
+
74
+
```bash
75
+
bun --hot src/index.ts
76
+
```
77
+
78
+
## Environment Variables
79
+
80
+
### Required
81
+
82
+
| Variable | Description | How to get |
83
+
|----------|-------------|------------|
84
+
| `TELEGRAM_BOT_TOKEN` | Bot token | Create bot via [@BotFather](https://t.me/BotFather) |
85
+
| `LETTA_BASE_URL` | Letta API URL | `http://localhost:8283` for dev |
86
+
| `ANTHROPIC_PROXY_URL` | Proxy URL | `http://localhost:4001/v1` for dev |
87
+
| `ANTHROPIC_PROXY_SESSION_SECRET` | Proxy secret | Generate: `openssl rand -hex 32` |
88
+
| `OPENAI_API_KEY` | OpenAI key | [platform.openai.com](https://platform.openai.com/api-keys) |
89
+
90
+
### Optional
91
+
92
+
| Variable | Default | Description |
93
+
|----------|---------|-------------|
94
+
| `PORT` | `3000` | Server port |
95
+
| `TELEGRAM_WEBHOOK_URL` | (empty) | Webhook URL for production |
96
+
| `TELEGRAM_WEBHOOK_SECRET_TOKEN` | (empty) | Webhook verification secret |
97
+
| `ANTHROPIC_PROXY_SESSION_ID` | (empty) | Filled after OAuth flow |
98
+
| `DB_PATH` | `./data/assistant.db` | SQLite database path |
99
+
100
+
## Telegram Bot Setup
101
+
102
+
1. Message [@BotFather](https://t.me/BotFather) on Telegram
103
+
2. Send `/newbot` and follow the prompts
104
+
3. Copy the bot token to `TELEGRAM_BOT_TOKEN` in `.env`
105
+
4. (Optional) Set bot commands via `/setcommands`:
106
+
```
107
+
start - Start the bot
108
+
help - Show help
109
+
dump - Brain dump mode
110
+
focus - Set current focus
111
+
wins - Show recent wins
112
+
```
113
+
114
+
### Webhook vs Polling
115
+
116
+
**Development (polling):** Leave `TELEGRAM_WEBHOOK_URL` empty. The bot will poll for updates.
117
+
118
+
**Production (webhook):** Set both:
119
+
```
120
+
TELEGRAM_WEBHOOK_URL=https://your-domain.com/webhook
121
+
TELEGRAM_WEBHOOK_SECRET_TOKEN=your_secret_here
122
+
```
123
+
124
+
## Docker Services
125
+
126
+
### View logs
127
+
128
+
```bash
129
+
# All services
130
+
docker compose logs -f
131
+
132
+
# Specific service
133
+
docker compose logs -f letta
134
+
docker compose logs -f anthropic-proxy
135
+
```
136
+
137
+
### Restart services
138
+
139
+
```bash
140
+
docker compose restart
141
+
```
142
+
143
+
### Stop services
144
+
145
+
```bash
146
+
docker compose down
147
+
```
148
+
149
+
### Rebuild (after Dockerfile changes)
150
+
151
+
```bash
152
+
docker compose build --no-cache anthropic-proxy
153
+
docker compose up -d
154
+
```
155
+
156
+
## Testing
157
+
158
+
```bash
159
+
# Run all tests
160
+
bun test
161
+
162
+
# Run specific test file
163
+
bun test src/config.test.ts
164
+
165
+
# Watch mode
166
+
bun test --watch
167
+
```
168
+
169
+
## Project Structure
170
+
171
+
```
172
+
├── src/
173
+
│ ├── config.ts # Environment configuration
174
+
│ ├── health.ts # Health check endpoints
175
+
│ ├── letta.ts # Letta client bootstrap
176
+
│ ├── index.ts # Main server (M1)
177
+
│ ├── bot.ts # Telegram bot (M1)
178
+
│ ├── db/ # Database schema (M2)
179
+
│ └── tools/ # Agent tools (M2+)
180
+
├── docker-compose.yml
181
+
├── docker-compose.dev.yml
182
+
├── Dockerfile.anthropic-proxy
183
+
└── .env.example
184
+
```
185
+
186
+
## Milestones
187
+
188
+
- [x] **M0**: Infrastructure (Docker, config, health, Letta client)
189
+
- [ ] **M1**: E2E Chat (Telegram bot, basic message flow)
190
+
- [ ] **M2**: Tools + Items (database, capture, breakdown)
191
+
- [ ] **M3**: Tone + Detection (overwhelm, self-bullying)
192
+
- [ ] **M4**: Tiny Wins (win tracking)
193
+
- [ ] **M5**: Threading (focus, deviations)
194
+
- [ ] **M6**: Hardening (idempotency, retries, tests)
10
195
196
+
## Troubleshooting
197
+
198
+
### "Missing required environment variable"
199
+
200
+
Make sure you've copied `.env.example` to `.env` and filled in all required values.
201
+
202
+
### Letta health check failing
203
+
204
+
Check if Letta is running:
11
205
```bash
12
-
bun run index.ts
206
+
curl http://localhost:8283/v1/health
207
+
```
208
+
209
+
If not responding, check logs:
210
+
```bash
211
+
docker compose logs letta
13
212
```
14
213
15
-
This project was created using `bun init` in bun v1.3.4. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
214
+
### Anthropic proxy not working
215
+
216
+
1. Verify the proxy is running: `curl http://localhost:4001/health`
217
+
2. Check if OAuth is complete (session ID should be set)
218
+
3. Check logs: `docker compose logs anthropic-proxy`
219
+
220
+
### Can't connect to Telegram
221
+
222
+
1. Verify bot token is correct
223
+
2. Check if another instance is running (only one can poll at a time)
224
+
3. For webhooks, ensure URL is publicly accessible with valid HTTPS