ai-atlasforge 1.3.3

Autonomous AI research and development platform powered by Claude

AI-AtlasForge

An autonomous AI research and development platform powered by Claude. Run long-duration missions, accumulate cross-session knowledge, and build software autonomously.

What is AI-AtlasForge?

AI-AtlasForge is not a chatbot wrapper. It's an autonomous research engine that:

• Runs multi-day missions without human intervention
• Maintains mission continuity across context windows
• Accumulates knowledge that persists across sessions
• Self-corrects when drifting from objectives
• Adversarially tests its own outputs

Quick Start

Prerequisites

• Python 3.10+
• Anthropic API key (get one at https://console.anthropic.com/)
• Linux environment (tested on Ubuntu 22.04+, Debian 12+)

Platform Notes:

• Windows: Use WSL2 (Windows Subsystem for Linux)
• macOS: Should work but is untested. Please report issues.

Option 1: Standard Installation

# Clone the repository
git clone https://github.com/DragonShadows1978/AI-AtlasForge.git
cd AI-AtlasForge

# Run the installer
./install.sh

# Configure your API key
export ANTHROPIC_API_KEY='your-key-here'
# Or edit config.yaml / .env

# Verify installation
./verify.sh

Option 2: One-Liner Install

curl -sSL https://raw.githubusercontent.com/DragonShadows1978/AI-AtlasForge/main/quick_install.sh | bash

Option 3: Docker Installation

git clone https://github.com/DragonShadows1978/AI-AtlasForge.git
cd AI-AtlasForge
docker compose up -d
# Dashboard at http://localhost:5050

For detailed installation options, see INSTALL.md or QUICKSTART.md.

Running Your First Mission

1. Start the Dashboard (optional, for monitoring):

   make dashboard
   # Or: python3 dashboard_v2.py
   # Access at http://localhost:5050
   

2. Create a Mission:

   • Via Dashboard: Click "Create Mission" and enter your objectives
   • Via Sample: Run make sample-mission to load a hello-world mission
   • Via JSON: Create state/mission.json manually

3. Start the Engine:

   make run
   # Or: python3 claude_autonomous.py --mode=rd
   

Development Commands

Run make help to see all available commands:

make install      # Full installation
make verify       # Verify installation
make dashboard    # Start dashboard
make run          # Start autonomous agent
make docker       # Start with Docker
make sample-mission  # Load sample mission

Architecture

                    +-------------------+
                    |   Mission State   |
                    |  (mission.json)   |
                    +--------+----------+
                             |
              +--------------+--------------+
              |                             |
    +---------v---------+         +--------v--------+
    |    AtlasForge     |         |    Dashboard    |
    | (Execution Engine)|         |   (Monitoring)  |
    +---------+---------+         +-----------------+
              |
    +---------v---------+
    |    R&D Engine     |
    |   (State Machine) |
    +---------+---------+
              |
    +---------v-------------------+
    |     Stage Pipeline          |
    |                             |
    |  PLANNING -> BUILDING ->    |
    |  TESTING -> ANALYZING ->    |
    |  CYCLE_END -> COMPLETE      |
    +-----------------------------+

Mission Lifecycle

1. PLANNING - Understand objectives, research codebase, create implementation plan
2. BUILDING - Implement the solution
3. TESTING - Validate implementation
4. ANALYZING - Evaluate results, identify issues
5. CYCLE_END - Generate reports, prepare continuation
6. COMPLETE - Mission finished

Missions can iterate through multiple cycles until success criteria are met.

Core Components

atlasforge.py

Main execution loop. Spawns Claude instances, manages state, handles graceful shutdown.

af_engine.py

State machine for mission execution. Manages stages, enforces constraints, tracks progress.

dashboard_v2.py

Web-based monitoring interface showing mission status, knowledge base, and analytics.

Knowledge Base

SQLite database accumulating learnings across all missions:

• Techniques discovered
• Insights gained
• Gotchas encountered
• Reusable code patterns

Adversarial Testing

Separate Claude instances that test implementations:

• RedTeam agents with no implementation knowledge
• Mutation testing
• Property-based testing

GlassBox

Post-mission introspection system:

• Transcript parsing
• Agent hierarchy reconstruction
• Stage timeline visualization

Key Features

Display Layer (Windows)

Visual environment for graphical application testing:

• Screenshot capture from virtual display
• Web-accessible display via noVNC (localhost:6080)
• Web terminal via ttyd (localhost:7681)
• Browser support for OAuth flows and web testing
• Automatic GPU detection with software fallback

See docs/DISPLAY_LAYER.md for the user guide.

Mission Continuity

Missions survive context window limits through:

• Persistent mission.json state
• Cycle-based iteration
• Continuation prompts that preserve context

Knowledge Accumulation

Every mission adds to the knowledge base. The system improves over time as it learns patterns, gotchas, and techniques.

Autonomous Operation

Designed for unattended execution:

• Graceful crash recovery
• Stage checkpointing
• Automatic cycle progression

Directory Structure

AI-AtlasForge/
+-- atlasforge.py           # Main entry point
+-- af_engine.py            # Stage state machine
+-- dashboard_v2.py         # Web dashboard
+-- adversarial_testing/    # Testing framework
+-- atlasforge_enhancements/  # Enhancement modules
+-- workspace/              # Active workspace
|   +-- glassbox/           # Introspection tools
|   +-- artifacts/          # Plans, reports
|   +-- research/           # Notes, findings
|   +-- tests/              # Test scripts
+-- state/                  # Runtime state
|   +-- mission.json        # Current mission
|   +-- claude_state.json   # Execution state
+-- missions/               # Mission workspaces
+-- atlasforge_data/
|   +-- knowledge_base/     # Accumulated learnings
+-- logs/                   # Execution logs

Configuration

AI-AtlasForge uses environment variables for configuration:

Variable	Default	Description
ATLASFORGE_PORT	5050	Dashboard port
ATLASFORGE_ROOT	(script directory)	Base directory
ATLASFORGE_DEBUG	false	Enable debug logging

Dashboard Features

The web dashboard provides real-time monitoring:

• Mission Status - Current stage, progress, timing
• Activity Feed - Live log of agent actions
• Knowledge Base - Search and browse learnings
• Analytics - Token usage, cost tracking
• Mission Queue - Queue and schedule missions
• GlassBox - Post-mission analysis

Philosophy

First principles only. No frameworks hiding integration failures. Every component built from scratch for full visibility.

Speed of machine, not human. Designed for autonomous operation. Check in when convenient, not when required.

Knowledge accumulates. Every mission adds to the knowledge base. The system gets better over time.

Trust but verify. Adversarial testing catches what regular testing misses. The same agent that writes code doesn't validate it.

Requirements

• Python 3.10+
• Node.js 18+ (optional, for dashboard JS modifications)
• Anthropic API key
• Linux environment (Ubuntu 22.04+, Debian 12+)

Python Dependencies

See requirements.txt or pyproject.toml for full list.

Documentation

• QUICKSTART.md - Get started in 5 minutes
• INSTALL.md - Detailed installation guide
• USAGE.md - How to use AI-AtlasForge
• ARCHITECTURE.md - System architecture
• DISPLAY_LAYER.md - Display Layer user guide (Windows)
• TROUBLESHOOTING.md - Display Layer troubleshooting

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Related Projects

• AI-AfterImage - Episodic memory for AI coding agents. Gives Claude Code persistent memory of code it has written across sessions. Works great with AtlasForge for cross-mission code recall.

Acknowledgments

Built on Claude by Anthropic. Special thanks to the Claude Code team for making autonomous AI development possible.