Skip to content

CLAUDE.md

Latest commit

 

History

History
116 lines (88 loc) · 4.43 KB

CLAUDE.md

File metadata and controls

116 lines (88 loc) · 4.43 KB

CLAUDE.md - Project Context for AI Assistants

Project Overview

ADK Claw is a personal AI assistant CLI tool with persistent memory, Telegram integration, and extensible skills. Built on top of @iqai/adk.

Tech Stack

  • Runtime: Node.js with ES Modules ("type": "module")
  • Language: TypeScript
  • Package Manager: pnpm
  • Build: tsc + cp (copies templates to dist)
  • Linting: Biome
  • Core Dependencies: @iqai/adk, @clack/prompts, @openrouter/ai-sdk-provider

Project Structure

adk-claw/
├── src/
│   ├── cli/           # CLI commands (init, start, etc.)
│   │   ├── index.ts   # CLI router
│   │   └── init.ts    # Init command - creates config and workspace
│   ├── agents/        # Agent definitions
│   ├── config/        # Configuration loading
│   ├── lib/           # Shared utilities
│   ├── memory/        # Memory system
│   ├── services/      # External services (Telegram, etc.)
│   ├── skills/        # Extensible skills system
│   ├── tools/         # Agent tools
│   ├── types/         # TypeScript types
│   └── index.ts       # Main entry point
├── templates/
│   └── workspace/     # Templates copied during init
│       ├── AGENTS.md  # Agent configuration template
│       ├── SOUL.md    # Agent personality template
│       ├── USER.md    # User profile template
│       └── .gitignore
├── dist/              # Compiled output (includes templates after build)
└── .adk-claw/         # User's local config (created by init, gitignored)
    ├── config.json    # User configuration (API keys, etc.)
    └── workspace/     # User's workspace with personalized templates

Key Commands

pnpm dev:cli          # Run CLI in dev mode (tsx)
pnpm build            # Build (tsc + copy templates to dist)
pnpm start            # Run built CLI
pnpm lint:fix         # Fix linting issues

Onboarding Flow (adk-claw init)

  1. User runs adk-claw init or pnpm dev:cli (defaults to init)
  2. Prompts collect: agent name, model, OpenRouter API key, Telegram bot token
  3. Creates .adk-claw/config.json with all settings
  4. Copies templates from templates/workspace/ to .adk-claw/workspace/:
    • AGENTS.md, SOUL.md, USER.md (with placeholder replacement)
    • Creates empty memory/ and skills/ directories (ADK MemoryService creates memory files automatically)
  5. Initializes git in workspace
  6. User runs adk-claw start to launch the agent

Template Placeholders

Templates use these placeholders that get replaced during init:

  • {{AGENT_NAME}} - User's chosen agent name
  • {{USER_NAME}} - Defaults to "default"
  • {{CREATED_DATE}} - ISO date string

Important Implementation Details

Template Path Resolution (src/cli/init.ts:14-17)

Templates must be found in both dev and built modes:

  • Dev mode (tsx src/cli/index.ts): Templates at project root templates/
  • Built mode (node dist/cli/index.ts): Templates at dist/templates/

The code checks which path exists and uses the appropriate one.

Build Process

The build script (package.json):

"build": "tsc && cp -r templates dist/"

This copies templates to dist/templates/ so the built CLI can find them.

Recent Changes / Session Log

2025-02-03: Fixed template copying during init

Problem: Running adk-claw init created the workspace directory structure but no .md files (AGENTS.md, SOUL.md, USER.md, memory files).

Root Cause: Two issues:

  1. Build script used cpx to copy templates, but cpx wasn't installed as a dependency
  2. Template path resolution only worked in built mode, not dev mode

Fix:

  1. Changed build script from cpx "templates/**/*" dist/templates to cp -r templates dist/
  2. Updated TEMPLATES_DIR resolution in src/cli/init.ts to check both paths:
    • First tries ../templates (built mode: dist/cli -> dist/templates)
    • Falls back to ../../templates (dev mode: src/cli -> templates)

Known Issues / TODOs

  • The @iqai/adk package may show warnings about missing CLI files (can be ignored)

Tips for Future Sessions

  • Always run pnpm build after making changes to test the built version
  • Templates are at project root templates/, NOT in src/
  • User config/workspace is in .adk-claw/ (gitignored, contains secrets)
  • Test both pnpm dev:cli AND pnpm build && pnpm cli to ensure both modes work