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

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) ✅

Browser Automation Tools (25 tools) ✅

Search & Edit Tools (2 tools) ✅

AppleScript Tools (1 tool) ✅

Configuration Tools (2 tools) ✅

Project structure

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

See also: docs/PROJECT-STRUCTURE.md

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

All tests passing! See

🧪 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

📊

🚀 Quick Start

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

Prerequisites

⚙️ Configuration Setup

Copy and customize configuration templates:

📋 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)

MCP server (for IDEs)

Option 3: Cloud MCP Mode (Remote Access)

✅ Verify Installation

📋 Usage Modes

Usage Mode Comparison

1. 🖥️ CLI Mode (100% Working)

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

Basic Task Management

Advanced CLI Usage

🎯 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

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

Priority Manipulation Commands

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

For complete documentation, see:

• Priority System Guide - Comprehensive documentation

• Migration Guide - Upgrading from string priorities

Automation Examples

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)

1. Open Cursor → Settings → MCP

2. 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

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):

⚠️ 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:

Option 2: Manual configuration

Add to your Claude Code MCP settings:

Option 3: Project-scoped setup

For team collaboration with shared MCP configuration:

Usage Examples in IDE

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

Available Tools in MCP Mode

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

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

Setup Cloud Deployment

Local Development with mcp-proxy

Test HTTP/SSE Endpoints

Cursor Configuration for Cloud Mode

Deploy to Google Cloud Platform

📚 Example Use Cases

1. Automated Project Setup

2. Code Review Automation

3. CI/CD Integration

4. Browser Testing Automation

🔧 Development & Testing

Run Tests

Development Setup

🐛 Troubleshooting

CLI Mode Issues

MCP Mode Issues

Cloud Mode Issues

🤝 Contributing

1. Fork the repository

2. Create a feature branch: git checkout -b feature/amazing-feature

3. Test your changes: node test-simple-tools.js

4. Commit your changes: git commit -m 'Add amazing feature'

5. Push to the branch: git push origin feature/amazing-feature

6. 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!

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