# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Repository Overview

This is a multi-project workspace for **Echo**, a personal AI assistant ecosystem owned by Marius. It contains three main components: a web dashboard, Python utility tools, and Antfarm (an agent workflow orchestration CLI).

**Language:** Romanian is used extensively in docs, variable names, and comments. Marius prefers no emojis in conversation.

## Project Structure

- **dashboard/** — Web-based task/habit tracking SPA (vanilla JS + Python backend via `api.py`)
- **antfarm/** — Multi-agent workflow orchestration CLI (TypeScript + Node.js + SQLite)
- **tools/** — Python utility scripts (email, calendar, git, YouTube, ANAF monitor, Ralph workflow)
- **memory/** — Knowledge base and daily notes (`memory/YYYY-MM-DD.md`, `memory/kb/`)
- **skills/** — Agent skill definitions

## Build & Run Commands

### Antfarm (TypeScript)
```bash
cd antfarm && npm run build    # tsc + copy HTML + chmod
cd antfarm && npm start        # node dist/cli/cli.js
antfarm install                # Install all bundled workflows
antfarm workflow run <id> <task>  # Start a workflow run
antfarm dashboard              # Web dashboard on port 3333
```
- Requires Node.js >= 22, ES modules (`"type": "module"`)
- TypeScript strict mode, target ES2022, module NodeNext
- No linter or formatter configured

### Dashboard (Python)
```bash
python3 dashboard/api.py       # Start HTTP server
pytest dashboard/tests/        # Run all dashboard tests
pytest dashboard/tests/test_habits_api.py  # Run a single test file
```

### Tools (Python)
```bash
python3 tools/youtube_subs.py URL [lang]
python3 tools/email_send.py "dest" "subject" "body"
python3 tools/email_process.py [--save|--all]
python3 tools/calendar_check.py [today|week|travel]
python3 tools/git_commit.py --push
python3 tools/ralph_workflow.py          # Autonomous code generation
```

## Architecture

### Antfarm — Multi-Agent Workflows
- **Workflow pattern:** YAML-defined pipelines where specialized agents (planner, developer, verifier, tester, reviewer) execute steps sequentially
- **Fresh context per step:** Each agent runs in a clean session — no shared context window
- **State in SQLite:** `~/.openclaw/antfarm/antfarm.db` with WAL mode; tables: `runs`, `steps`, `stories`
- **Cron-based polling:** Agents poll for work at configurable intervals (120s–300s)
- **Tool-gating by role:** agents have restricted tool access (e.g., `verification` role = read + exec, NO write)
- **Bundled workflows:** `feature-dev` (7 agents), `bug-fix` (6 agents), `security-audit` (7 agents)
- **Key source files:** `src/cli/cli.ts` (entry), `src/db.ts` (SQLite), `src/installer/install.ts` (workflow provisioning), `src/installer/workflow-spec.ts` (YAML parsing), `src/installer/step-ops.ts` (step claim/complete/fail), `src/server/dashboard.ts` (HTTP API)

### Dashboard — Habit Tracker & Task Board
- **Single-page app** with swipe navigation between pages (index, habits, notes, files, workspace)
- **Backend:** Python `SimpleHTTPRequestHandler` with `/api/` routing in `dashboard/api.py`
- **Data:** JSON files (`habits.json`, `todos.json`, `tasks.json`, `status.json`)
- **Frontend:** Vanilla JS + CSS with Lucide icons, design tokens for light/dark themes
- **Served over Tailscale:** `https://moltbot.tailf7372d.ts.net/echo/`

### Ralph — Autonomous Code Generation
- Opus generates PRD/stories, Sonnet implements them
- `tools/ralph_prd_generator.py` → PRD + `prd.json`
- `tools/ralph_workflow.py` → launches the full loop
- Projects go in `~/workspace/`

## Key Configuration

- **AGENTS.md** — Agent behavior rules, model selection (Haiku/Sonnet/Opus), security policies
- **USER.md** — Marius's profile, preferences, and 80/20 work style
- **TOOLS.md** — Available tools with exact CLI invocations
- **antfarm/workflows/{id}/workflow.yml** — YAML workflow definitions
- **antfarm/agents/shared/** — Shared agent definitions (setup, verifier, pr)

## Conventions

- **Model selection:** Opus for planning/architecture, Sonnet for implementation/coding, Haiku for routine tasks
- **80/20 rule:** Minimal effort, maximum results — avoid over-engineering
- **Security:** Never store secrets in code; use `.env` files; `trash` over `rm`; confirm destructive actions
- **Git:** Main branch is `master`; remote is `gitea.romfast.ro/romfast/clawd`