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:

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

Coding Agent (Every Session)

When you run monty code:

Reads progress file and git logs to understand current state
Runs health checks and validates environment
Selects highest-priority failing feature
Implements feature incrementally
Tests using browser automation
Updates feature status and commits changes
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:

Cannot delete features from the feature list
Cannot modify test steps (steps are immutable after creation)
Cannot modify descriptions after creation
Must verify via browser before marking features as passing
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:

First attempt to auto-detect Claude Code credentials
If not found, offer OAuth login (opens browser) or manual API Key entry
Validate your credentials
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:

ANTHROPIC_SUBSCRIPTION_KEY environment variable
ANTHROPIC_API_KEY environment variable
Subscription key from ~/.monty/credentials.json
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:

For Claude Code subscription: Run claude login to refresh, then monty login
For API key: Get a new key from console.anthropic.com/settings/keys
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

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

Contributing

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

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

References

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: jeremyw@dobeu.net
Website: dobeu.net
Terms of Service: dobeu.net/tos
Privacy Policy: dobeu.net/privacy

See LICENSE for full details.

Made with Claude Agent SDK

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
.agent		.agent
.claude		.claude
.github/workflows		.github/workflows
bin		bin
scripts		scripts
src		src
templates		templates
tests		tests
.cursorrules		.cursorrules
.gitignore		.gitignore
AUTONOMOUS_WORKFLOWS.md		AUTONOMOUS_WORKFLOWS.md
BEST_PRACTICES.md		BEST_PRACTICES.md
CLAUDE.md		CLAUDE.md
FEATURE_PROPOSAL.md		FEATURE_PROPOSAL.md
LICENSE		LICENSE
README.md		README.md
agent.ts		agent.ts
monty-ai-fullstackdev-coder.code-workspace		monty-ai-fullstackdev-coder.code-workspace
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
utils.py		utils.py
vitest.config.ts		vitest.config.ts

License

dobeutech/monty-ai-fullstackdev-coder

Folders and files

Latest commit

History

Repository files navigation

Monty Full-Stack Agent

Installation

Prerequisites

Windows Installation

macOS Installation

Linux Installation

Run Directly with npx (No Install)

Project-Level Installation

Alternative Package Managers

Quick Start

Starting a New Project

Using with an Existing Codebase

Resuming Work

Commands

Authentication Commands

Options

How It Works

Two-Agent Architecture

Initializer Agent (First Run)

Coding Agent (Every Session)

Feature Detection

Files Created

Feature List Format

Feature Categories

Poka-yoke Safeguards

Best Practices

Failure Modes Addressed

Configuration

Development

Building from Source

Project Structure

Authentication

1. Auto-Detection (Primary)

2. Interactive Login

3. Environment Variables

Authentication Priority

Troubleshooting

Authentication Issues

"Authentication required"

"Token expired"

"Could not validate credentials"

Debugging Authentication

Other Issues

"Feature list not found"

"Permission denied"

Agent fails to start

Contributing

References

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

Packages