Monty Full-Stack Agent

An autonomous full-stack development agent powered by the Claude Agent SDK. Takes your project from idea to production with incremental progress tracking across multiple sessions.

Based on Anthropic's best practices for long-running agents.

Installation

Prerequisites

• Node.js >= 18.0.0
• Claude Code Subscription or Anthropic API Key - Sign in with monty login or get a key at console.anthropic.com

Windows Installation

# 1. Install Node.js (if not installed)
# Download from https://nodejs.org or use winget:
winget install OpenJS.NodeJS.LTS

# 2. Install Monty globally
npm install -g @dobeutechsolutions/monty-fullstack-agent

# 3. Authenticate (RECOMMENDED - interactive login)
monty login

# 3b. Or set API key manually (PowerShell - current session)
$env:ANTHROPIC_API_KEY="your-api-key-here"

# 3c. Or set API key permanently (PowerShell - persistent)
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "your-api-key-here", "User")

# 4. Verify installation
monty --help

macOS Installation

# 1. Install Node.js (if not installed)
# Using Homebrew (recommended):
brew install node

# Or download from https://nodejs.org

# 2. Install Monty globally
npm install -g @dobeutechsolutions/monty-fullstack-agent

# 3. Authenticate (RECOMMENDED - interactive login)
monty login

# 3b. Or set API key manually (current session)
export ANTHROPIC_API_KEY="your-api-key-here"

# 3c. Or set API key permanently (add to ~/.zshrc or ~/.bash_profile)
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

# 4. Verify installation
monty --help

Linux Installation

# 1. Install Node.js (if not installed)
# Ubuntu/Debian:
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Fedora/RHEL:
sudo dnf install nodejs

# Arch Linux:
sudo pacman -S nodejs npm

# Or use nvm (all distros):
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

# 2. Install Monty globally
npm install -g @dobeutechsolutions/monty-fullstack-agent

# 3. Authenticate (RECOMMENDED - interactive login)
monty login

# 3b. Or set API key manually (current session)
export ANTHROPIC_API_KEY="your-api-key-here"

# 3c. Or set API key permanently (add to ~/.bashrc or ~/.zshrc)
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

# 4. Verify installation
monty --help

Run Directly with npx (No Install)

# Works on all platforms - no installation needed
npx @dobeutechsolutions/monty-fullstack-agent --help

# Initialize a new project
npx @dobeutechsolutions/monty-fullstack-agent init --spec="Build a todo app with React and Supabase"

# Continue development
npx @dobeutechsolutions/monty-fullstack-agent code

Project-Level Installation

# Add to an existing project
npm install --save-dev @dobeutechsolutions/monty-fullstack-agent

# Add scripts to package.json:
# "scripts": {
#   "agent:init": "monty init",
#   "agent:code": "monty code"
# }

Alternative Package Managers

# Yarn
yarn global add @dobeutechsolutions/monty-fullstack-agent

# pnpm
pnpm add -g @dobeutechsolutions/monty-fullstack-agent

# Bun
bun add -g @dobeutechsolutions/monty-fullstack-agent

Quick Start

Starting a New Project

# Create a new directory
mkdir my-awesome-app && cd my-awesome-app

# Initialize with your idea
monty init --spec="Build a modern todo app with React, TypeScript, Tailwind CSS, and Supabase backend. Include user authentication, real-time updates, and dark mode."

# Continue development
monty code

Using with an Existing Codebase

# Navigate to your existing project
cd your-existing-project

# Initialize Monty (it will detect your tech stack)
monty init --spec="Complete the authentication system and add user dashboard"

# The agent will analyze your codebase and create a feature list
# Continue with incremental development
monty code

Resuming Work

# Check project status
monty status

# Continue where you left off
monty code

# Add specific context for this session
monty code --context="Focus on fixing the login bug in auth.ts"

Commands

| Command | Description | |---------|-------------| | monty | Auto-detect mode (shows help if not initialized) | | monty init | Initialize a new project with feature list | | monty code | Continue incremental development | | monty status | Show project progress and feature status | | monty setup | Set up Monty in current directory | | monty --help | Show detailed help |

Authentication Commands

| Command | Description | |---------|-------------| | monty login | Sign in with Claude Code subscription or Anthropic API key | | monty logout | Sign out and clear stored credentials | | monty whoami | Show current authentication status |

Options

| Option | Description | |--------|-------------| | --spec="..." | Project specification for initialization | | --context="..." | Additional context for coding session | | --help, -h | Show help | | --version, -v | Show version |

How It Works

Two-Agent Architecture

Monty uses a sophisticated two-agent system:

┌─────────────────┐     First Run     ┌─────────────────┐
│                 │ ───────────────── │   Initializer   │
│   Your Idea     │                   │      Agent      │
│                 │                   │                 │
└─────────────────┘                   └────────┬────────┘
                                               │
                                               │ Creates
                                               ▼
                                      ┌─────────────────┐
                                      │ .agent/         │
                                      │ - feature_list  │
                                      │ - progress.txt  │
                                      └────────┬────────┘
                                               │
┌─────────────────┐   Subsequent      ┌────────▼────────┐
│   Production    │ ◄──────────────── │    Coding       │
│   Ready App     │     Runs          │    Agent        │
│                 │                   │                 │
└─────────────────┘                   └─────────────────┘

Initializer Agent (First Run)

When you first run monty init:

1. Analyzes your project specification
2. Detects existing tech stack (if any)
3. Generates comprehensive feature_list.json with ALL features marked as passes: false
4. Creates claude-progress.txt for session bridging
5. Makes initial git commit

Coding Agent (Every Session)

When you run monty code:

1. Reads progress file and git logs to understand current state
2. Runs health checks and validates environment
3. Selects highest-priority failing feature
4. Implements feature incrementally
5. Tests using browser automation
6. Updates feature status and commits changes
7. Logs progress for the next session

Feature Detection

Monty automatically detects and adapts to:

Frameworks: React, Next.js, Vue, Svelte, Angular, Vanilla JS Build Tools: Vite, Webpack, Rollup, Turbopack Testing: Vitest, Jest, Playwright, Cypress Backend: Supabase, Express, Fastify, Next.js API Databases: PostgreSQL, MySQL, MongoDB, SQLite Styling: Tailwind CSS, CSS Modules, Styled Components, SASS Package Managers: npm, yarn, pnpm, bun

Files Created

your-project/
└── .agent/                        # Monty's working directory
    ├── feature_list.json          # Feature tracking (immutable structure)
    ├── claude-progress.txt        # Session logs for context bridging
    ├── error-log.json             # Error history for recovery
    └── checkpoints.json           # Recovery checkpoints

Feature List Format

{
  "project": {
    "name": "My App",
    "description": "A modern todo application",
    "created_at": "2025-01-15T00:00:00Z",
    "stack": ["react", "typescript", "tailwind", "supabase"]
  },
  "features": [
    {
      "id": "feat-001",
      "category": "functional",
      "priority": 1,
      "description": "User can create new todo items",
      "steps": [
        "Navigate to main interface",
        "Click 'Add Todo' button",
        "Enter todo text",
        "Verify todo appears in list"
      ],
      "passes": false,
      "last_tested": null,
      "notes": ""
    }
  ]
}

Feature Categories

• functional - Core application logic and features
• ui - User interface elements, styling, responsiveness
• integration - API calls, data flow, third-party services
• performance - Loading times, optimizations
• accessibility - Keyboard navigation, screen readers, ARIA

Poka-yoke Safeguards

The framework enforces these rules to prevent common agent failures:

1. Cannot delete features from the feature list
2. Cannot modify test steps (steps are immutable after creation)
3. Cannot modify descriptions after creation
4. Must verify via browser before marking features as passing
5. Must commit changes before ending a session

Best Practices

Based on Anthropic's documentation:

| Best Practice | Implementation | |--------------|----------------| | Incremental Progress | Work on ONE feature at a time | | Clean State | Always leave codebase in committable state | | Browser Verification | Test as a human user would | | Progress Logging | Document everything for the next session | | Git Discipline | Descriptive commits for every change |

Failure Modes Addressed

| Problem | Solution | |---------|----------| | Agent declares victory too early | Feature list requires ALL features to pass | | Leaves environment with bugs | Must verify via browser before marking done | | Marks features done prematurely | Browser automation required for verification | | Spends time figuring out setup | Automated project detection and init scripts | | Loses context between sessions | claude-progress.txt + git logs |

Configuration

For advanced customization, modify src/config/agent-config.ts:

export const agentConfig = {
  paths: {
    agentDir: '.agent',
    featureList: '.agent/feature_list.json',
    progressFile: '.agent/claude-progress.txt',
  },
  tools: {
    initializer: ['Read', 'Write', 'Bash', 'Glob'],
    coding: ['Read', 'Edit', 'Bash', 'Glob', 'Browser'],
  },
  permissionMode: 'acceptEdits',
  session: {
    maxRetries: 3,
    autoCommit: true,
  },
};

Development

Building from Source

# Clone the repository
git clone https://github.com/dobeutech/monty-ai-fullstackdev-coder.git
cd monty-ai-fullstackdev-coder

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

Project Structure

monty-fullstack-agent/
├── bin/
│   └── cli.js                 # CLI entry point
├── src/
│   ├── agents/
│   │   ├── initializer.ts     # First-run setup agent
│   │   ├── coding.ts          # Incremental progress agent
│   │   └── prompts/           # System prompts
│   ├── config/
│   │   ├── agent-config.ts    # Shared configuration
│   │   └── mcp-config.ts      # Browser automation settings
│   ├── utils/                 # Utility modules
│   └── index.ts               # Main entry point
├── templates/                 # File templates
└── scripts/                   # Init scripts

Authentication

Monty supports multiple authentication methods:

1. Auto-Detection (Primary)

If you are already authenticated with Claude Code, Monty will automatically detect and import your credentials.

monty login
# ✓ Found Claude Code credentials!
# ✓ Imported successfully

2. Interactive Login

# Sign in with Claude Code subscription (OAuth) or Anthropic API key
monty login

# Check your authentication status
monty whoami

# Sign out when needed
monty logout

The interactive login will:

1. First attempt to auto-detect Claude Code credentials
2. If not found, offer OAuth login (opens browser) or manual API Key entry
3. Validate your credentials
4. Store them securely in ~/.monty/credentials.json

3. Environment Variables

You can also authenticate using environment variables:

| Variable | Description | Required | |----------|-------------|----------| | ANTHROPIC_API_KEY | Anthropic API key | No (if using login) | | ANTHROPIC_SUBSCRIPTION_KEY | Claude Code subscription key | No (if using login) | | FORCE_INIT | Force initialization mode | No |

Authentication Priority

When multiple credential sources exist, the priority is:

1. ANTHROPIC_SUBSCRIPTION_KEY environment variable
2. ANTHROPIC_API_KEY environment variable
3. Subscription key from ~/.monty/credentials.json
4. API key from ~/.monty/credentials.json

Troubleshooting

Authentication Issues

"Authentication required"

You need to authenticate before using Monty. Choose one of these methods:

Option 1: Auto-detect (recommended) - If you have Claude Code CLI installed:

# First, authenticate with Claude Code
claude login

# Then let Monty auto-detect your credentials
monty login

Option 2: Manual API Key:

# Interactive login
monty login
# Select "API Key" method
# Paste your key from console.anthropic.com

# OR set environment variable
export ANTHROPIC_API_KEY="sk-ant-..."

Option 3: Environment Variable (for automation/CI):

export ANTHROPIC_API_KEY="your-key-here"
monty init --spec="your project"

"Token expired"

Monty automatically refreshes expired tokens if you authenticated via Claude Code CLI.

If auto-refresh fails, re-authenticate:

monty logout
monty login

"Could not validate credentials"

Your API key may be invalid or expired:

1. For Claude Code subscription: Run claude login to refresh, then monty login
2. For API key: Get a new key from console.anthropic.com/settings/keys
3. Check your key: Run monty whoami to verify authentication status

Debugging Authentication

Check your current authentication status:

monty whoami

This command shows:

• Authentication method (Claude subscription or API key)
• Token expiration (if applicable)
• Key preview (first 8 and last 4 characters)
• Credential source (environment variable or file)

If authentication is working but agents fail:

• Verify network connectivity to api.anthropic.com
• Check that credentials file permissions are correct:
  • Unix/Mac: ls -la ~/.monty/credentials.json (should be -rw-------)
  • Windows: Only current user should have access
• Try setting API key directly: export ANTHROPIC_API_KEY="your-key"

Other Issues

"Feature list not found"

Run monty init first to initialize the project:

monty init --spec="Build a todo app with React"

"Permission denied"

Ensure the CLI is executable:

# Unix/Mac
chmod +x $(which monty)

# Windows (run as Administrator if needed)
# No action usually required on Windows

Agent fails to start

1. Check authentication: monty whoami
2. Verify Node.js version: node --version (must be >= 18.0.0)
3. Check for error messages in the output
4. Try running with explicit auth: ANTHROPIC_API_KEY="your-key" monty code

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

References

• Effective Harnesses for Long-Running Agents
• Building Effective Agents
• Demystifying Evals for AI Agents
• Claude Agent SDK

License

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License (CC BY-NC 4.0).

You are free to:

• Share and redistribute the material
• Adapt, remix, and build upon the material

Under these terms:

• Attribution - You must give appropriate credit to Dobeu Tech Solutions LLC
• NonCommercial - You may not use the material for commercial purposes

For commercial licensing:

• Email: [email protected]
• Website: dobeu.net
• Terms of Service: dobeu.net/tos
• Privacy Policy: dobeu.net/privacy

See LICENSE for full details.

Copyright (c) 2025 Dobeu Tech Solutions LLC - All Rights Reserved

Made with Claude Agent SDK