Agentic Control Framework (ACF)

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

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

- 🔧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

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.

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

- getContextreturns the exact task/subtask context block (including related files metadata and activity log).
- generateTaskFilesmaterializes one Markdown file per task (tasks/), andtasks-table.mdgives a project overview.
- CLIcontext <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_blockapplies surgical replacements using explicit old/new blocks (minimizes accidental drift).
- Execution: terminal tools (execute_command,list_processes, sessions) to verify context assumptions (tests, builds).

- File watcher syncstasks.jsonand per‑task files; debounced change detection;tasks-table.mdkept fresh.
- Guards:allowedDirectoriesandreadonlyModerestrict the accessible filesystem scope.

- parsePrd,expandTask,reviseTasksconvert 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.

- tools/call: parsePrd { filePath }→ tasks created with priorities and dependencies →generateTaskFilesfor review.

- tools/call: getNextTask→ get the next actionable task considering dependencies/priority.
- tools/call: getContext { id }→ fetch the task block; thenread_file/search_codefor surrounding code.

- Retrieve:search_codeto identify exact block; verify withread_file.
- Apply:edit_block { file_path, old_string, new_string, normalize_whitespace }.
- Verify:execute_command { command: "npm test" }or suite‑specific commands.

- start_file_watcher→ modify files or tasks →file_watcher_statusfor stats →stop_file_watcherwhen 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.jsonand per‑task files: