clawd/CLAUDE.md

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)

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)

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)

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