Agentic Control Framework (ACF)

Author: Abhilash Chadhar (FutureAtoms) Repository: agentic-control-framework

AI‑native orchestration layer (CLI + MCP) with 80+ tools for context engineering—retrieval, code editing, browser automation, terminal orchestration, and persistent memory—designed for Claude Code, Cursor, Codex, and VS Code. This README reflects the current code and tested integrations.

CLI entry: bin/acf
MCP server: bin/agentic-control-framework-mcp → src/mcp/server.js
Example client configs: config/examples/
Tests: npm run test:cli, npm test

What’s included

What’s in the box

Task manager with priorities, dependencies, subtasks, templates
CLI with rich commands
MCP server (JSON‑RPC over stdio) tested with Claude Desktop/Code, Cursor, Codex

Key Features:

🔧 80+ Specialized Tools: Task management, filesystem, terminal, browser automation, AppleScript integration
🎯 3 Usage Modes: CLI, Local MCP, Cloud MCP for maximum flexibility
🔗 Universal Compatibility: Works with Claude Code, Cursor, Claude Desktop, VS Code, and any MCP-compatible client
☁️ Cloud-Ready: Deploy to GCP, Railway, Fly.io with auto-scaling
🚀 Production-Ready: Comprehensive test suite coverage across core tools
⚡ High Performance: Average response time 200-1000ms, excellent reliability
🛡️ Security-First: Filesystem guardrails, permission systems, and secure defaults
📋 MCP 2025-03-26 Compliant: Default protocol with tool titles, annotations, and proper capabilities

How ACF Solves Context Engineering

ACF turns the messy, multi-file, multi-step reality of software work into precise, addressable “context units” that LLMs can request, refine, and act on. It does this by combining a task graph, rich context surfaces, retrieval/edit tools, and guardrails — all accessible via CLI and MCP.

Task Graph as Source of Truth
- Each task/subtask has an ID, status, numeric priority (1–1000), dependencies, related files, activity log, timestamps.
- Priority engine supports time decay and effort weighting to keep “what’s next” dynamically correct.
Rich, On‑Demand Context Surfaces
- getContext returns the exact task/subtask context block (including related files metadata and activity log).
- generateTaskFiles materializes one Markdown file per task (tasks/), and tasks-table.md gives a project overview.
- CLI context <id> prints a human summary for humans and LLMs.
Retrieval and Editing Tools (for context building and application)
- Retrieval: search_code, tree, list_directory, get_file_info, read_file/read_multiple_files, read_url.
- Editing: edit_block applies surgical replacements using explicit old/new blocks (minimizes accidental drift).
- Execution: terminal tools (execute_command, list_processes, sessions) to verify context assumptions (tests, builds).
Synchronization & Freshness
- File watcher syncs tasks.json and per‑task files; debounced change detection; tasks-table.md kept fresh.
- Guards: allowedDirectories and readonlyMode restrict the accessible filesystem scope.
Planning from Product Docs (optional)
- parsePrd, expandTask, reviseTasks convert PRDs or change requests into structured tasks via Gemini, then fold back into the task graph for traceable execution.

Together, this provides a repeatable “context loop”: plan → retrieve → edit/verify → update state, with every step addressable by tools so MCP clients (Claude Code, Cursor, Codex, VS Code) can drive it reliably.

End‑to‑End Context Recipes

Bootstrap from PRD
- tools/call: parsePrd { filePath } → tasks created with priorities and dependencies → generateTaskFiles for review.
Focus a Model on the Next Action
- tools/call: getNextTask → get the next actionable task considering dependencies/priority.
- tools/call: getContext { id } → fetch the task block; then read_file/search_code for surrounding code.
Safe, Surgical Code Change
- Retrieve: search_code to identify exact block; verify with read_file.
- Apply: edit_block { file_path, old_string, new_string, normalize_whitespace }.
- Verify: execute_command { command: "npm test" } or suite‑specific commands.
Keep Context Fresh
- start_file_watcher → modify files or tasks → file_watcher_status for stats → stop_file_watcher when done.

Persistent Memory (Activity Logs in tasks.json)

ACF keeps a durable, queryable memory of what the agent (or human) did, when, and why. This persistent memory lives in .acf/tasks.json and per‑task files:

What is stored
- For every task and subtask: createdAt, updatedAt, and activityLog[] entries with timestamped messages.
- Each change to a task (status, title, description, priority, dependencies, related files) appends a log entry and bumps updatedAt.
- AI flows (parsePrd, expandTask, reviseTasks) also write clear activity messages.
How LLMs write memory
- CLI: include --message "..." when changing state to append a human/LLM note to the activity log.
  - Examples:
    - acf status 12 inprogress --message "Started implementing parser"
    - acf update 12 --priority 750 --message "Raised priority due to deadline"
- MCP: pass message in tools/call arguments for updateStatus or updateTask.
  - tools/call { name: "updateStatus", arguments: { id: "12", newStatus: "done", message: "Tests green; merging" } }
  - tools/call { name: "updateTask", arguments: { id: "12", priority: 820, message: "Escalated after stakeholder review" } }
How to consume memory
- acf context <id> (CLI) prints a rich, human‑readable context including the recent activityLog.
- tools/call: getContext { id } (MCP) returns the same structured block, ideal for LLM prompts.
- generateTaskFiles produces markdown snapshots; tasks-table.md shows a live overview synced from .acf/tasks.json via the file watcher.

Quick Start

Requirements
- Node.js 18+
- macOS for AppleScript tools (optional). Playwright browsers if using browser tools: npx playwright install.
Install
- cd agentic-control-framework && npm ci
CLI (local)
- ./bin/acf init --project-name "Demo" --project-description "Getting started"
- ./bin/acf add -t "First task" -p high
- ./bin/acf list --format human
MCP Server (stdio)
- node ./bin/agentic-control-framework-mcp --workspaceRoot $(pwd)
- Use example client configs in config/examples/ for Claude Code, Cursor, and Codex.

Documentation

Overview
- Primary docs index: docs/README.md
- Project structure: docs/PROJECT-STRUCTURE.md
- Architecture overview: docs/architecture/overview.md
- MCP integration details: docs/architecture/mcp-integration.md
Integrations (MCP Clients)
- Connection guides: docs/INTEGRATIONS.md
- Example configs:
  - Claude Code (VS Code): config/examples/claude_code.json
  - Cursor (project/global): config/examples/cursor.mcp.json
  - Codex CLI (TOML): config/examples/codex.config.toml
- Claude helper (dev notes): CLAUDE.md
Reference
- CLI complete examples: docs/reference/cli_examples.md
- MCP request/response examples (auto‑generated): docs/reference/mcp_examples.md
Testing & Validation
- Test summary and notes: docs/TESTING_SUMMARY.md
- Doc command validator: scripts/testing/validate-doc-commands.sh
Proposals & Ideas
- Workspace indexing proposal: docs/workspace-indexing-proposal.md

MCP tools (implemented)

Tool Categories Overview

mindmap
  root((ACF Tools<br/>79 Total))
    Core ACF
      Task Management
        listTasks
        addTask
        updateStatus
        getNextTask
      Priority System
        recalculatePriorities
        getPriorityStatistics
        bumpTaskPriority
        prioritizeTask
      File Watching
        initializeFileWatcher
        stopFileWatcher
        forceSyncTaskFiles
      Templates
        getPriorityTemplates
        addTaskWithTemplate
    File Operations
      Basic Operations
        read_file
        write_file
        copy_file
        delete_file
      Directory Ops
        list_directory
        create_directory
        tree
        search_files
    Terminal
      Command Execution
        execute_command
        read_output
        force_terminate
      Process Management
        list_processes
        kill_process
    Browser Automation
      Navigation
        browser_navigate
        browser_navigate_back
        browser_close
      Interaction
        browser_click
        browser_type
        browser_hover
        browser_drag
      Capture
        browser_take_screenshot
        browser_pdf_save
        browser_snapshot
      Tab Management
        browser_tab_list
        browser_tab_new
        browser_tab_close
    Search & Edit
      search_code
      edit_block
    System Integration
      AppleScript
        applescript_execute
      Configuration
        get_config
        set_config_value

Core task tools

initProject, addTask, addSubtask, listTasks, updateTask, updateStatus, removeTask, getNextTask
generateTaskFiles, recalculatePriorities, getPriorityStatistics, getDependencyAnalysis
getPriorityTemplates, calculatePriorityFromTemplate, suggestPriorityTemplate, addTaskWithTemplate

Utilities

read_file, write_file
execute_command (stub for tests)

Note: Tools are advertised via tools/list from src/mcp/server.js, and each listed tool has a handler in the server.

Configuration

Core environment variables
- WORKSPACE_ROOT: default workspace path used by CLI/MCP
- ALLOWED_DIRS: additional allowed directories (path-delimited)
- READONLY_MODE: set to true to disable write operations
- ACF_PATH: project root override for bins
Optional/feature flags
- GEMINI_API_KEY: enable AI-backed tools (parsePrd, expandTask, reviseTasks)
- ACF_SKIP_POSTINSTALL=1: skip all postinstall steps
- ACF_SKIP_PLAYWRIGHT=1: skip heavy Playwright browser downloads
- ACF_INSTALL_SHARP=1 or ACF_INSTALL_ALL=1: install optional sharp
- ACF_ENABLE_BROWSER_TOOLS=1: enable Playwright browser tests (macOS default)
- ACF_ENABLE_APPLESCRIPT=1: enable AppleScript tests (macOS only)

Security & Guardrails

Filesystem access is constrained by allowedDirectories and readonlyMode.
URL reads (read_url) are explicit; edits use edit_block with old/new content to minimize unintended changes.
Terminal execution supports blocked commands and timeouts; sessions can be listed/terminated.

CLI commands (high level)

init, add, list, add-subtask, status, next, update, remove, context
update-subtask, bump, defer, prioritize, deprioritize
recalculate-priorities, priority-stats, dependency-analysis
start-file-watcher, stop-file-watcher, file-watcher-status, force-sync
list-templates, suggest-template, calculate-priority, add-with-template

Terminal Tools (6 tools) ✅

Command Execution:
- execute_command: Run shell commands with timeout
- read_output: Read from running processes
- force_terminate: Kill processes
- list_sessions: Show active terminal sessions
- list_processes: Show running processes
- kill_process: Terminate processes

Browser Automation Tools (25 tools) ✅

Navigation:
- browser_navigate: Navigate to URLs
- browser_navigate_back: Go back
- browser_navigate_forward: Go forward
- browser_close: Close browser

Interaction:
- browser_click: Click elements
- browser_type: Type text
- browser_hover: Hover over elements
- browser_drag: Drag and drop
- browser_select_option: Select dropdown options
- browser_press_key: Keyboard input

Capture:
- browser_take_screenshot: Screenshots
- browser_snapshot: Accessibility snapshots
- browser_pdf_save: Save as PDF

Management:
- browser_tab_list: List browser tabs
- browser_tab_new: Open new tabs
- browser_tab_select: Switch tabs
- browser_tab_close: Close tabs
- browser_file_upload: Upload files
- browser_wait: Wait for time/conditions
- browser_resize: Resize window
- browser_handle_dialog: Handle alerts/dialogs
- browser_console_messages: Get console logs
- browser_network_requests: Monitor network

Search & Edit Tools (2 tools) ✅

Code Operations:
- search_code: Advanced text/code search with ripgrep
- edit_block: Surgical text replacements

AppleScript Tools (1 tool) ✅

macOS Automation:
- applescript_execute: Run AppleScript for system integration

Configuration Tools (2 tools) ✅

Server Management:
- get_config: Get server configuration
- set_config_value: Update configuration values

Project structure

The repository is organized following standard practices with clean separation of concerns:

agentic-control-framework/
├── 📁 bin/           # CLI executables and entry points
├── 📁 src/           # Core source code and tool implementations
├── 📁 docs/          # Comprehensive documentation (organized by category)
├── 📁 test/          # Testing infrastructure and test suites
├── 📁 config/        # Configuration files and examples
├── 📁 scripts/       # Setup, deployment, and maintenance scripts
├── 📁 deployment/    # Cloud deployment configurations
├── 📁 tasks/         # Task management files
├── 📁 templates/     # Project templates
├── 📁 public/        # Static assets
└── 📁 data/          # Data directory

Integrations

Use the ready-to-copy templates in config/examples/.

Claude Desktop: claude.json
Claude Code (VS Code): config/examples/claude_code.json
Cursor: config/examples/cursor.mcp.json
Codex: config/examples/codex.config.toml

More details: docs/INTEGRATIONS.md

☁️ Cloud Deployment

Deployment Guide - Complete deployment overview

Testing

MCP tests: npm test
CLI tests: npm run test:cli
Coverage: npm run coverage:all

Environment flags

ACF_SKIP_POSTINSTALL=1 to skip all postinstall steps
ACF_SKIP_PLAYWRIGHT=1 to skip Playwright browser downloads on install
ACF_INSTALL_SHARP=1 (or ACF_INSTALL_ALL=1) to install optional sharp
ACF_ENABLE_BROWSER_TOOLS=1 to enable Playwright browser tests (macOS only by default)
ACF_ENABLE_APPLESCRIPT=1 to enable AppleScript tests (macOS only)

Platform gating (CI-safe by default)

Browser and AppleScript MCP tests are skipped by default and on Windows/Linux.
To run them locally on macOS, set the corresponding ACF_ENABLE_* env vars.
Google Cloud Run - GCP deployment
Docker - Container deployment
Remote Setup - Remote client configuration

🧪 Testing & Quality

Cloud MCP Testing - Latest comprehensive testing
Tool Verification - All 79 tools verified
Security Testing - Security validation
Test Framework - Testing infrastructure

🏗️ Technical Reference

System Architecture - Complete architecture with diagrams
Tool Reference - Complete tool documentation
Priority System - Advanced task prioritization
MCP Integration - Protocol implementation details
Project Structure - Repository organization
Quick Reference - Essential commands

📋 Complete Documentation Index

Master Documentation Index - Complete catalog of all documentation
Documentation Index - Quick reference index

📊 Current Status

Component	Status	Details
CLI Mode	✅ 100% Working	All task management and core tools functional
Local MCP	✅ 100% Working	All core tools verified via MCP protocol
Cloud MCP	✅ 100% Working	mcp-proxy integration, HTTP/SSE transport verified
IDE Integrations	✅ 100% Working	Cursor, Claude Desktop, Claude Code, VS Code tested
Core ACF Tools	✅ 25/25 Working	Task management, priority system, file generation
Filesystem Tools	✅ 14/14 Working	File operations, directory management, search
Browser Tools	✅ 25/25 Working	Playwright automation, screenshots, PDF generation
Terminal Tools	✅ 6/6 Working	Command execution, process management
Search/Edit Tools	✅ 3/3 Working	Code search with ripgrep, surgical editing
System Tools	✅ 7/7 Working	AppleScript, configuration management
MCP Protocol	✅ Supported	JSON-RPC 2.0; MCP 2025-03-26 (default) and 2024-11-05

All tests passing! See ACF-TESTING-SUMMARY.md for detailed test results

🧪 Test Results & Quality Assurance

Latest Test Run: 100% Pass Rate (All Tests Passing)

✅ Comprehensive Test Coverage

CLI Tool Tests: ✅ PASSED - All task management operations working
Local MCP Tool Tests: ✅ PASSED - 3/3 core tests, 100% success rate
stdio MCP Tool Tests: ✅ PASSED - 25/25 comprehensive tests, 100% success rate
Specialized Tool Tests: ✅ PASSED - Filesystem, Browser, AppleScript, Search, Edit tools
Integration Tests: ✅ PASSED - MCP proxy, client configurations, SSE endpoints
End-to-End Tests: ✅ PASSED - System health check, all modules loading

📊 Performance Metrics

Average Response Time: 24ms
Maximum Response Time: 439ms
No Slow Responses: 0 responses >1s
No Large Responses: 0 responses >10KB
Quality Assessment: EXCELLENT (100% pass rate)

🔧 Validated Features

Task management workflow with dependencies
Priority system and recalculation
MCP protocol compliance and communication
Browser automation with Playwright
AppleScript integration (macOS)
Filesystem operations with security guardrails
Search and edit tool functionality
Client configuration generation (Cursor, Claude Desktop, VS Code)

🧪 Testing & Verification

Comprehensive Testing Completed (January 2025)

ACF has undergone extensive testing to ensure production readiness:

Tool Verification ✅

Extensive tool testing: Core tools verified via MCP protocol
100% Success Rate: All tools working correctly across all categories
Performance Validated: Average 4ms response time, no slow responses

IDE Integration Testing ✅

Claude Code: 15/15 compatibility tests passed
Cursor IDE: Configuration and tool discovery verified
Claude Desktop: SSE transport and mcp-proxy integration tested
VS Code: Cline and Continue extension configurations verified

Protocol Compliance ✅

MCP 2025-03-26: Default protocol version; backward compatible with 2024-11-05
JSON-RPC 2.0: Full protocol implementation
Error Handling: Standard error codes and graceful degradation

📊 View Complete Testing Report

🚀 Quick Start

📋 Need detailed setup instructions? See our comprehensive Platform Setup Guide for Windows, macOS, and Ubuntu with step-by-step instructions.

Prerequisites

# Install Node.js 22+ (LTS)
node --version

# Install dependencies
npm install

# Install global MCP dependencies (for IDE integration)
npm install -g mcp-proxy @modelcontextprotocol/inspector

# Install browser dependencies (for automation tools)
npx playwright install

# Make CLI tools executable (macOS/Linux)
chmod +x bin/*

⚙️ Configuration Setup

Copy and customize configuration templates:

# Copy configuration templates
cp config/examples/config.json ./config.json
cp config/examples/claude-mcp-config.json ./claude-mcp-config.json

# Update paths in configuration files
export ACF_PATH="$(pwd)"
export WORKSPACE_ROOT="$(pwd)"

# Replace placeholders (Linux/macOS)
sed -i 's|${ACF_PATH}|'$ACF_PATH'|g' *.json
sed -i 's|${WORKSPACE_ROOT}|'$WORKSPACE_ROOT'|g' *.json

# Or set environment variables instead
echo 'export ACF_PATH="'$(pwd)'"' >> ~/.bashrc
echo 'export WORKSPACE_ROOT="'$(pwd)'"' >> ~/.bashrc

📋 Need help with configuration? See config/README.md for detailed setup instructions.

🚀 Start ACF Server

Choose your preferred mode:

Option 1: CLI Mode (Direct Commands)

# Initialize project
./bin/acf init --project-name "My Project" --project-description "Getting started with ACF"

# Start using CLI commands
./bin/acf add --title "First Task" --description "Test ACF functionality" --priority high
./bin/acf list

MCP server (for IDEs)

node ./bin/agentic-control-framework-mcp --workspaceRoot $(pwd)

Option 3: Cloud MCP Mode (Remote Access)

# Terminal 1: Start ACF MCP Server
node ./bin/agentic-control-framework-mcp --workspaceRoot $(pwd)

# Terminal 2: Start mcp-proxy for HTTP/SSE access
mcp-proxy --port 8080 node ./bin/agentic-control-framework-mcp --workspaceRoot $(pwd)

# Server available at http://localhost:8080

✅ Verify Installation

# Test CLI functionality
./bin/acf --help

# Test MCP server (in separate terminal)
curl -X POST http://localhost:8080/stream -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'  # If using mcp-proxy

# Run test suite
npm test

📋 Usage Modes

Usage Mode Comparison

graph LR
    subgraph "CLI Mode"
        CLI1[Direct Commands]
        CLI2[Automation Scripts]
        CLI3[CI/CD Integration]
    end

    subgraph "Local MCP Mode"
        MCP1[Claude Code]
        MCP2[Cursor IDE]
        MCP3[Claude Desktop]
        MCP4[VS Code]
    end

    subgraph "Remote MCP Mode"
        REM1[Web Clients]
        REM2[Distributed Teams]
        REM3[Cloud Deployment]
        REM4[Multi-Client Access]
    end

    CLI1 --> |Fast & Direct| ACF[ACF Core]
    CLI2 --> |Scriptable| ACF
    CLI3 --> |Automated| ACF

    MCP1 --> |Natural Language| ACF
    MCP2 --> |IDE Integration| ACF
    MCP3 --> |AI Assistant| ACF
    MCP4 --> |Extension| ACF

    REM1 --> |HTTP/SSE| PROXY[mcp-proxy]
    REM2 --> |Remote Access| PROXY
    REM3 --> |Scalable| PROXY
    REM4 --> |Concurrent| PROXY

    PROXY --> ACF

    ACF --> TOOLS[80+ Tools]

    style CLI1 fill:#e1f5fe
    style MCP1 fill:#f3e5f5
    style REM1 fill:#e8f5e8
    style ACF fill:#fff3e0
    style TOOLS fill:#fce4ec

1. 🖥️ CLI Mode (100% Working)

Perfect for: Automated scripts, local development, CI/CD integration

Basic Task Management

# Initialize project
cd your-project
./path/to/acf/bin/acf init -n "My Project" -d "Project description"

# Add tasks
./path/to/acf/bin/acf add -t "Implement feature" -d "Add new functionality" -p high

# List tasks
./path/to/acf/bin/acf list

# Update task status
./path/to/acf/bin/acf status 1 inprogress -m "Started working"

# Add subtasks
./path/to/acf/bin/acf add-subtask 1 -t "Write tests"

# Get next actionable task
./path/to/acf/bin/acf next

# Generate task files
./path/to/acf/bin/acf generate

Advanced CLI Usage

# Update task details
./path/to/acf/bin/acf update 1 -p medium --related-files "src/main.js,test/main.test.js"

# Get task context
./path/to/acf/bin/acf get-context 1

# Remove completed tasks
./path/to/acf/bin/acf remove 1

# Generate markdown table
./path/to/acf/bin/acf list --table

🎯 Numerical Priority System (1-1000)

ACF features a sophisticated numerical priority system that replaces traditional 4-level priorities with a flexible 1-1000 scale, providing fine-grained control and intelligent dependency management.

Priority System Architecture

graph TD
    subgraph "Priority Ranges"
        CRIT[🚨 Critical<br/>900-1000<br/>Security, Blockers]
        HIGH[🔴 High<br/>700-899<br/>Important Features]
        MED[🟡 Medium<br/>400-699<br/>Standard Work]
        LOW[🟢 Low<br/>1-399<br/>Documentation]
    end

    subgraph "Priority Engine"
        PE[Priority Engine]
        DA[Dependency Analysis]
        TA[Time Decay]
        EW[Effort Weighting]
        UT[Uniqueness Tracker]
    end

    subgraph "Algorithms"
        DB[Dependency Boosts]
        CP[Critical Path]
        DO[Distribution Optimization]
        AR[Auto Recalculation]
    end

    subgraph "Operations"
        BUMP[Bump Priority]
        DEFER[Defer Priority]
        PRIO[Prioritize]
        DEPRIO[Deprioritize]
        RECALC[Recalculate All]
    end

    PE --> DA
    PE --> TA
    PE --> EW
    PE --> UT

    DA --> DB
    DA --> CP
    PE --> DO
    PE --> AR

    BUMP --> PE
    DEFER --> PE
    PRIO --> PE
    DEPRIO --> PE
    RECALC --> PE

    PE --> CRIT
    PE --> HIGH
    PE --> MED
    PE --> LOW

    style CRIT fill:#ffebee
    style HIGH fill:#fff3e0
    style MED fill:#f9fbe7
    style LOW fill:#e8f5e8
    style PE fill:#e3f2fd

Priority Ranges

🟢 Low (1-399): Documentation, cleanup, nice-to-have features
🟡 Medium (400-699): Standard development work, regular features
🔴 High (700-899): Important features, significant bugs, urgent tasks
🚨 Critical (900-1000): Security fixes, blocking issues, production emergencies

Basic Priority Usage

# Using numerical priorities (1-1000)
./bin/acf add "Critical security fix" --priority 950
./bin/acf add "Feature implementation" --priority 650
./bin/acf add "Documentation update" --priority 200

# Using string priorities (backward compatible)
./bin/acf add "Bug fix" --priority high
./bin/acf add "Cleanup task" --priority low

Priority Manipulation Commands

# Increase priority by amount
./bin/acf bump 123 --amount 100

# Decrease priority by amount
./bin/acf defer 123 --amount 50

# Set to high priority range (700-899)
./bin/acf prioritize 123

# Set to low priority range (1-399)
./bin/acf deprioritize 123

# View priority statistics and distribution
./bin/acf priority-stats

# Analyze dependencies and critical paths
./bin/acf dependency-analysis

# Trigger intelligent priority recalculation
./bin/acf recalculate-priorities

Advanced Priority Features

🔄 Automatic Uniqueness: Every task gets a unique priority value
📈 Dependency Boosts: Tasks with dependents automatically get priority increases
🔗 Critical Path Analysis: Identifies and prioritizes bottleneck tasks
⚡ Intelligent Recalculation: Optimizes priorities based on dependencies and time
📊 Distribution Optimization: Prevents priority clustering and maintains meaningful differences

Priority Display Formats

# Clean table format (default)
./bin/acf list --table
┌─────┬────────────────────┬──────────┐
│ ID  │ Title              │ Priority │
├─────┼────────────────────┼──────────┤
│ 24  │ Critical Bug Fix   │ 950      │
│ 25  │ Feature Request    │ 650      │
└─────┴────────────────────┴──────────┘

# Human-readable with distribution stats
./bin/acf list --human
📊 Priority Distribution:
🚨 Critical (900+): 2 | 🔴 High (700-899): 5 | 🟡 Medium (500-699): 8 | 🟢 Low (<500): 3

For complete documentation, see:

Priority System Guide - Comprehensive documentation
Migration Guide - Upgrading from string priorities

Automation Examples

# Daily standup automation
#!/bin/bash
echo "📊 Daily Standup Report"
echo "======================="
./bin/acf list --status inprogress
echo ""
echo "Next Priority Tasks:"
./bin/acf next

# CI/CD Integration
#!/bin/bash
# In your CI pipeline
./bin/acf add -t "Deploy v$VERSION" -d "Deploy to production" -p high
./bin/acf status $TASK_ID done -m "Deployed successfully"

2. 🔗 Local MCP Mode (100% Working)

Perfect for: IDE integration (Cursor, Claude Desktop, Claude Code), local development

Cursor Configuration

Option 1: Via Cursor Settings UI (Recommended)

Open Cursor → Settings → MCP
Add new server:
- Name: acf-local
- Command: node
- Args: ["/path/to/agentic-control-framework/bin/agentic-control-framework-mcp", "--workspaceRoot", "/path/to/your/project"]
- Environment:
```
{
  "WORKSPACE_ROOT": "/path/to/your/project",
  "ALLOWED_DIRS": "/path/to/your/project:/tmp",
  "READONLY_MODE": "false"
}
```

Option 2: Via settings.json

{
  "mcp.servers": {
    "acf-local": {
      "command": "node",
      "args": [
        "/path/to/agentic-control-framework/bin/agentic-control-framework-mcp",
        "--workspaceRoot",
        "/path/to/your/project"
      ],
      "env": {
        "WORKSPACE_ROOT": "/path/to/your/project",
        "ALLOWED_DIRS": "/path/to/your/project:/tmp",
        "READONLY_MODE": "false"
      }
    }
  }
}

Claude Desktop Configuration

⚠️ IMPORTANT: Use ONLY the Direct Executable Method - This is the ONLY method confirmed to work reliably

Configuration File Location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Configuration (replace with your actual paths):

{
  "mcpServers": {
    "agentic-control-framework": {
      "command": "/FULL/PATH/TO/agentic-control-framework/bin/agentic-control-framework-mcp",
      "env": {
        "ACF_PATH": "/FULL/PATH/TO/agentic-control-framework",
        "WORKSPACE_ROOT": "/FULL/PATH/TO/YOUR/WORKSPACE",
        "ALLOWED_DIRS": "/FULL/PATH/TO/YOUR/WORKSPACE:/tmp",
        "READONLY_MODE": "false",
        "BROWSER_HEADLESS": "false",
        "DEFAULT_SHELL": "/bin/bash"
      }
    }
  }
}

⚠️ CRITICAL REQUIREMENTS:

Use FULL ABSOLUTE PATHS - no relative paths or ~
Set ACF_PATH to your ACF installation directory
Set WORKSPACE_ROOT to your project workspace
Ensure bin/agentic-control-framework-mcp is executable: chmod +x bin/agentic-control-framework-mcp
❌ DO NOT USE the node + args pattern - it fails in Claude Desktop

Claude Code Configuration

Option 1: Using Claude MCP commands (Recommended)

Configure ACF as an MCP server using Claude's built-in commands:

# Navigate to your project directory
cd your-project-directory

# Add ACF as an MCP server
claude mcp add acf-server \
  -e ACF_PATH="/path/to/agentic-control-framework" \
  -e WORKSPACE_ROOT="$(pwd)" \
  -e READONLY_MODE="false" \
  -e BROWSER_HEADLESS="false" \
  -e DEFAULT_SHELL="/bin/bash" \
  -e NODE_ENV="production" \
  -- node /path/to/agentic-control-framework/bin/agentic-control-framework-mcp --workspaceRoot "$(pwd)"

# Start Claude with ACF tools available
claude

Option 2: Manual configuration

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "agentic-control-framework": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/path/to/agentic-control-framework/bin/agentic-control-framework-mcp",
        "--workspaceRoot",
        "/path/to/your/project"
      ],
      "env": {
        "ACF_PATH": "/path/to/agentic-control-framework",
        "WORKSPACE_ROOT": "/path/to/your/project",
        "READONLY_MODE": "false",
        "BROWSER_HEADLESS": "false",
        "DEFAULT_SHELL": "/bin/bash",
        "NODE_ENV": "production"
      }
    }
  }
}

Option 3: Project-scoped setup

For team collaboration with shared MCP configuration:

# Navigate to your project directory
cd /path/to/your/project

# Add ACF as project-scoped MCP server (shared with team)
claude mcp add acf-project -s project \
  -e ACF_PATH="/path/to/agentic-control-framework" \
  -e WORKSPACE_ROOT="$(pwd)" \
  -e READONLY_MODE="false" \
  -- node /path/to/agentic-control-framework/bin/agentic-control-framework-mcp --workspaceRoot "$(pwd)"

# This creates a .mcp.json file that can be committed to version control
# Team members can then use: claude

# Start Claude with shared ACF tools
claude

Usage Examples in IDE

Once configured, you can use natural language with your AI assistant:

"Add a new high-priority task for implementing user authentication"

"Create a critical priority task (950) for fixing the security vulnerability"

"List all tasks that are currently in progress"

"Show me priority statistics and distribution of all tasks"

"Bump the priority of task #123 by 100 points"

"Analyze dependencies and show me the critical path"

"Read the contents of src/main.js and create a task for adding error handling"

"Execute the test suite and create a task if there are failures"

"Search for all TODO comments in the codebase and create tasks for them"

"Take a screenshot of the application login page"

"Write a new file called docs/api.md with API documentation"

"Recalculate all task priorities with dependency boosts enabled"

Available Tools in MCP Mode

Category	Tools	Status
Task Management	listTasks, addTask, updateStatus, getNextTask, priority tools	✅ Working
Filesystem	read_file, write_file, list_directory, search_files	✅ Working
Terminal	execute_command, list_processes, kill_process	✅ Working
Browser	navigate, click, type, screenshot, pdf_save	✅ Working
Search/Edit	search_code, edit_block	✅ Working
AppleScript	applescript_execute (macOS only)	✅ Working

3. ☁️ Cloud MCP Mode (100% Working)

Perfect for: Remote access, web clients, multi-client support

Setup Cloud Deployment

Local Development with mcp-proxy

# Install mcp-proxy
npm install -g mcp-proxy

# Start ACF with mcp-proxy
export WORKSPACE_ROOT="/path/to/your/project"
export ALLOWED_DIRS="/path/to/your/project:/tmp"

mcp-proxy --port 8080 node bin/agentic-control-framework-mcp --workspaceRoot "$WORKSPACE_ROOT"

Test HTTP/SSE Endpoints

# Test connectivity (should return error about session ID - this is expected)
curl -X POST http://localhost:8080/stream \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'

# MCP initialization (requires proper session handling)
curl -X POST http://localhost:8080/stream \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

# List available tools
curl -X POST http://localhost:8080/stream \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# Call a tool
curl -X POST http://localhost:8080/stream \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"listTasks","arguments":{}}}'

Cursor Configuration for Cloud Mode

{
  "mcp.servers": {
    "acf-cloud": {
      "transport": "sse",
      "endpoint": "http://localhost:8080/sse"
    }
  }
}

Deploy to Google Cloud Platform

# Authenticate
gcloud auth login

# Create project
gcloud projects create acf-your-name-$(date +%s)
export GCP_PROJECT_ID="your-project-id"

# Deploy
./quick-deploy.sh gcp --proxy-only

📚 Example Use Cases

1. Automated Project Setup

# CLI approach
./bin/acf init -n "E-commerce App" -d "Build online store"
./bin/acf add -t "Setup project structure" -p high
./bin/acf add -t "Configure database" -p high
./bin/acf add -t "Implement user auth" -p medium
./bin/acf add -t "Add payment integration" -p medium
./bin/acf add -t "Deploy to production" -p low

2. Code Review Automation

// MCP approach - ask your AI assistant:
"Search the codebase for any TODO comments and create tasks for each one"
"Read all JavaScript files in src/ and create tasks for any functions missing error handling"
"Take a screenshot of the app and create a task for any UI issues you notice"

3. CI/CD Integration

#!/bin/bash
# In your GitHub Actions workflow
- name: Update project tasks
  run: |
    ./bin/acf add -t "Test release v${{ github.event.release.tag_name }}" -p high
    ./bin/acf status $TASK_ID inprogress -m "Running tests for ${{ github.sha }}"
    
    # Run tests
    npm test
    
    if [ $? -eq 0 ]; then
      ./bin/acf status $TASK_ID done -m "Tests passed"
    else
      ./bin/acf status $TASK_ID error -m "Tests failed"
    fi

4. Browser Testing Automation

// Via MCP in your IDE
"Navigate to our staging site and take screenshots of the login, dashboard, and profile pages"
"Fill out the contact form with test data and take a screenshot of the success page"
"Test the mobile responsiveness by resizing to phone dimensions and taking screenshots"

🔧 Development & Testing

Run Tests

# Comprehensive test suite
node test-simple-tools.js

# Individual component tests
./test-all-tools-comprehensive.sh

Development Setup

# Clone repository
git clone https://github.com/your-org/agentic-control-framework.git
cd agentic-control-framework

# Install dependencies
npm install

# Setup development environment
chmod +x bin/*
export WORKSPACE_ROOT="$(pwd)"
export ALLOWED_DIRS="$(pwd):/tmp"

# Test CLI mode
./bin/acf list

# Test MCP mode
node bin/agentic-control-framework-mcp

🐛 Troubleshooting

CLI Mode Issues

# Check if tasks.json exists
ls -la tasks.json

# Verify permissions
chmod +x bin/acf

# Check Node.js version
node --version  # Should be 22+

MCP Mode Issues

# Check environment variables
echo $WORKSPACE_ROOT
echo $ALLOWED_DIRS

# Test MCP server directly
node bin/agentic-control-framework-mcp --help

# Check file permissions
ls -la bin/agentic-control-framework-mcp

Cloud Mode Issues

# Check mcp-proxy installation
npm list -g mcp-proxy

# Test proxy connectivity
curl -X POST http://localhost:8080/stream -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'

# Check proxy logs
mcp-proxy --port 8080 --debug node bin/agentic-control-framework-mcp --workspaceRoot $(pwd)

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Test your changes: node test-simple-tools.js
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Testing Guidelines

All new tools must have CLI, MCP, and Cloud tests
Maintain or improve the current test coverage (68%+)
Add examples to this README for new functionality

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

MCP Protocol: For standardized AI-tool communication
Playwright: For browser automation capabilities
Commander.js: For excellent CLI interface
mcp-proxy: For HTTP/SSE bridge functionality

🚀 Ready to build your autonomous agent? Choose your mode and get started!

Mode	Use Case	Setup Time	Status	Test Results
CLI	Scripts, automation	2 minutes	✅ Production Ready	100% Pass Rate
Local MCP	IDE integration	5 minutes	✅ Production Ready	25/25 Tests Passing
Cloud MCP	Remote access	15 minutes	✅ Production Ready	Full Integration Verified

For detailed test results and improvement roadmap, see ACF-TESTING-SUMMARY.md.