linear-coding-agent/.claude/CLAUDE.md

CLAUDE.md

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

Comportement de l'assistant

For Autonomous Agent: When running via autonomous_agent_demo.py, the agent should work autonomously without requesting confirmation for file modifications or code changes. The agent is trusted to implement features according to Linear issue specifications.

Overview

This is an autonomous coding agent framework that uses Claude Agent SDK with Linear integration for project management. The framework enables long-running autonomous development sessions where agents create complete applications from XML specifications.

Key Architecture: Two-agent pattern (Initializer + Coding Agent) with Linear as the single source of truth for project state and progress tracking.

Common Commands

Running the Agent

# Fresh project initialization
python autonomous_agent_demo.py --project-dir ./my_project

# Continue existing project
python autonomous_agent_demo.py --project-dir ./my_project

# Add new features to existing project (Initializer Bis)
python autonomous_agent_demo.py --project-dir ./my_project --new-spec app_spec_theme_customization.txt

# Limit iterations for testing
python autonomous_agent_demo.py --project-dir ./my_project --max-iterations 3

Testing

# Run security hook tests
python test_security.py

# Test mypy type checking (for library projects)
mypy path/to/module.py

Environment Setup

# Generate Claude Code OAuth token
claude setup-token

# Install dependencies
pip install -r requirements.txt

High-Level Architecture

Core Agent Flow

1. First Run (Initializer Agent):

   • Reads prompts/app_spec.txt specification
   • Creates Linear project and ~50 issues (one per <feature_X> tag)
   • Creates META issue for session tracking
   • Initializes project structure with init.sh
   • Writes .linear_project.json marker file

2. Subsequent Runs (Coding Agent):

   • Queries Linear for highest-priority Todo issue
   • Updates issue status to "In Progress"
   • Implements feature using SDK tools
   • Tests implementation (Puppeteer for web apps, pytest/mypy for libraries)
   • Adds comment to Linear issue with implementation notes
   • Marks issue as "Done"
   • Updates META issue with session summary

3. Initializer Bis (Add Features):

   • Triggered by --new-spec flag on existing projects
   • Reads new spec file from prompts/
   • Creates additional Linear issues for new features
   • Updates existing project without re-initializing

Key Design Patterns

Session Handoff via Linear: Agents don't use local state files for coordination. All session context, implementation notes, and progress tracking happens through Linear issues and comments. This provides:

• Real-time visibility in Linear workspace
• Persistent history across sessions
• Easy debugging via issue comments

Defense-in-Depth Security (see security.py and client.py):

1. OS-level sandbox for bash command isolation
2. Filesystem restrictions (operations limited to project directory)
3. Bash command allowlist with pre-tool-use hooks
4. Explicit MCP tool permissions

Project Type Detection (agent.py:is_library_project):

• Detects library/type-safety projects vs full-stack web apps
• Uses different coding prompts (coding_prompt_library.md vs coding_prompt.md)
• Keywords: "type safety", "docstrings", "mypy", "library rag"

Module Responsibilities

• autonomous_agent_demo.py: Entry point, argument parsing, environment validation
• agent.py: Core agent loop, session orchestration, project type detection
• client.py: Claude SDK client configuration, MCP server setup (Linear + Puppeteer)
• security.py: Bash command validation with allowlist, pre-tool-use hooks
• prompts.py: Prompt loading utilities, spec file copying
• progress.py: Progress tracking via .linear_project.json marker
• linear_config.py: Linear API configuration constants

MCP Servers

Linear (HTTP transport at mcp.linear.app/mcp):

• Project/team management
• Issue CRUD operations
• Comments and status updates
• Requires LINEAR_API_KEY in .env

Puppeteer (stdio transport):

• Browser automation for UI testing
• Navigate, screenshot, click, fill, evaluate
• Used by web app projects, not library projects

Application Specification Format

Specifications use XML format in prompts/app_spec.txt:

<project_specification>
  <project_name>Your App Name</project_name>
  <overview>Detailed description...</overview>

  <technology_stack>
    <frontend>...</frontend>
    <backend>...</backend>
  </technology_stack>

  <core_features>
    <feature_1>
      <title>Feature title</title>
      <description>Detailed description</description>
      <priority>1-4 (1=urgent, 4=low)</priority>
      <category>frontend|backend|auth|etc</category>
      <test_steps>
        1. Step one
        2. Step two
      </test_steps>
    </feature_1>
    <!-- More features... -->
  </core_features>
</project_specification>

Important: Each <feature_X> tag becomes a separate Linear issue. The initializer creates exactly one issue per feature tag.

Environment Configuration

All configuration via .env file (copy from .env.example):

CLAUDE_CODE_OAUTH_TOKEN='your-oauth-token'  # From: claude setup-token
LINEAR_API_KEY='lin_api_xxxxx'              # From: linear.app/settings/api
LINEAR_TEAM_ID='team-id'                    # Optional, agent prompts if missing

Security Model

Allowed Commands (security.py:ALLOWED_COMMANDS)

File operations: ls, cat, head, tail, wc, grep, cp, mkdir, chmod Development: npm, node, python, python3, mypy, pytest Version control: git Process management: ps, lsof, sleep, pkill Scripts: init.sh

Additional Validation

• pkill: Only allowed for dev processes (node, npm, vite, next)
• chmod: Only +x mode permitted (making scripts executable)
• init.sh: Must be ./init.sh or end with /init.sh

Adding New Commands

Edit security.py:ALLOWED_COMMANDS and optionally add validation logic to bash_security_hook.

Generated Project Structure

After initialization, projects contain:

my_project/
├── .linear_project.json      # Linear state marker (project_id, total_issues, meta_issue_id)
├── .claude_settings.json     # Security settings (auto-generated)
├── app_spec.txt              # Original specification (copied from prompts/)
├── init.sh                   # Environment setup script (executable)
└── [generated code]          # Application files created by agent

Creating New Applications

1. Create prompts/app_spec.txt with your XML specification
2. Use existing spec files as templates (see prompts/app_spec.txt for Claude Clone example)
3. Run: python autonomous_agent_demo.py --project-dir ./new_app
4. Monitor progress in Linear workspace

See GUIDE_NEW_APP.md for detailed guide (French).

Prompt Templates

Located in prompts/:

• initializer_prompt.md: First session prompt (creates Linear project/issues)
• initializer_bis_prompt.md: Add features prompt (extends existing project)
• coding_prompt.md: Standard coding session (web apps with Puppeteer testing)
• coding_prompt_library.md: Library coding session (focuses on types/docs, uses pytest/mypy)

The framework automatically selects the appropriate prompt based on session type and project detection.

Important Implementation Notes

Linear Integration

• All work tracked as Linear issues, not local files
• Session handoff via Linear comments on META issue
• Status workflow: Todo → In Progress → Done
• Early termination: Agent stops when detecting "feature-complete" in responses

Auto-Continue Behavior

Agent auto-continues with 3-second delay between sessions (agent.py:AUTO_CONTINUE_DELAY_SECONDS). Stops when:

• --max-iterations limit reached
• Response contains "feature-complete" or "all issues completed"
• Fatal error occurs

Project Directory Handling

Relative paths automatically placed under generations/ directory unless absolute path provided.

Model Selection

Default: claude-opus-4-5-20251101 (Opus 4.5 for best coding performance) Override with: --model claude-sonnet-4-5-20250929