Fathom Flow - Motor de Planejamento para Agentes IA
dwakianda-dot/fathom-mode-for-cowork
Planejamento estruturado com matriz de risco para agentes IA
Ver no GitHubCamada de orquestração de tarefas que introduz previsualizacao cognitiva estruturada para agentes de código IA, como Claude e assistentes gerais. Mapeia dependências, pontos de ambiguidade e requisitos de recursos antes da execução, transformando fluxos caóticos em processos deliberados, auditáveis e revisáveis.
Instalação
npx convez-ai dwakianda-dot/fathom-mode-for-cowork1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação segura de código com agentes IA
- Orquestração de tarefas complexas multi-etapas
- Auditoria e rastreabilidade de decisões de IA
- Mapeamento de dependências e identificação de riscos antes da execução
Veredito

Ferramenta inovadora que endereça um problema real em automação com IA—a falta de planejamento deliberado. A matriz de previsualizacao cognitiva é conceitual sólida, mas o projeto parece ainda em estágio early (arquitetura incompleta no README). Útil para quem quer controle fino sobre execução de agentes IA, requer expertise técnica considerável.
README
A tradução para o português deste README ainda está na fila.
Fathom Flow: Context-Aware Task Previsualization for AI Agents
Fathom Flow is a novel task orchestration layer designed for AI coding agents, including Claude Code and general-purpose assistants. Unlike traditional planning modes that merely pause execution, Fathom Flow introduces a cognitive previsualization matrix—a structured system where the agent maps out dependencies, ambiguity points, and resource requirements before a single line of code is written. Think of it as a blue-sky architect drawing a bridge's stress points before the first steel beam arrives.
This project transforms the chaotic "react-and-regret" workflow into a deliberate, reviewable, and auditable process. It is not a replacement for Claude's native planning mode but a supplement that adds granularity, risk assessment, and human-readable traceability to complex multi-step tasks.
graph TD
A[User Request] --> B{Fathom Flow Trigger}
B --> C[Intent Clarification Phase]
C --> D[Dependency Mapping]
D --> E[Risk & Ambiguity Flagging]
E --> F[Resource Estimation]
F --> G[Reviewable Plan Compilation]
G --> H{User Approval}
H -->|Approved| I[Execution Phase]
H -->|Rejected| J[Iterative Refinement]
J --> C
I --> K[Post-Execution Audit Log]
Table of Contents
- Why Fathom Flow Exists
- Core Architecture
- Installation & First Steps
- Example Profile Configuration
- Example Console Invocation
- Emoji OS Compatibility Table
- Feature Deep Dive
- AI Integration: OpenAI & Claude APIs
- Responsive UI & Multilingual Support
- 24/7 Customer Support Philosophy
- SEO-Friendly Ecosystem
- MIT License
- Disclaimer
Why Fathom Flow Exists
Modern AI agents are like sprinters who skip warm-ups. They charge into complex tasks, making assumptions, skipping edge cases, and leaving a trail of half-baked solutions. Fathom Flow is the warm-up routine, the stretching, and the pre-race nutrition for your AI assistant.
The core insight? Complexity is not a single leap but a series of informed decisions. By forcing the agent to articulate its intended path, surface hidden assumptions, and estimate the cognitive load of each step, Fathom Flow turns your AI from a gung-ho cowboy into a meticulous engineer.
Key Differentiator: Most "planning modes" simply pause execution. Fathom Flow actively precompiles the task into a structured decision tree, complete with fallback scenarios. It's the difference between a to-do list and a Gantt chart.
Core Architecture
Fathom Flow operates as a lightweight middleware that sits between your request and the agent's action space. It does not modify the agent's underlying model—instead, it injects a constraint layer that triggers a structured prompt sequence.
The Cognitive Previsualization Matrix
This is the heart of Fathom Flow. The matrix consists of five orthogonal axes:
- Intent Fidelity: How closely does the user's expressed intent match the likely execution path? (0-100%)
- Dependency Depth: How many cascading actions are required? (1-10)
- Ambiguity Index: How many unclear terms or open-ended statements exist? (0-100%)
- Resource Weight: Estimated compute time, API calls, or file modifications.
- Risk Profile: Probability of failure for each step (low/medium/high).
When a task enters Fathom Flow, the agent scores itself across these axes. The result is a visualizable heat map of task complexity.
flowchart LR
subgraph Input
A[Raw User Query]
end
subgraph Matrix_Construction
B[Parse Intent]
C[Decompose Steps]
D[Score Axes]
end
subgraph Output
E[Reviewable Plan]
F[Risk Heat Map]
G[Recommendations]
end
A --> B
B --> C
C --> D
D --> E
D --> F
D --> G
Installation & First Steps
Prerequisites
- Python 3.10 or higher
- A compatible AI agent (Claude Code, OpenAI GPT-4, or custom API endpoint)
- Basic familiarity with YAML configuration files
Quick Install
pip install fathom-flow
Or, for development:
git clone https://dwakianda-dot.github.io
cd fathom-flow
pip install -e .
Verify Installation
fathom-flow --version
You should see output similar to: Fathom Flow v1.2.0 (2026)
Example Profile Configuration
Fathom Flow uses profiles to adapt to different use cases. Below is a sample configuration for a software refactoring agent.
File: ~/.fathom-flow/profiles/refactoring.yaml
profile_name: "Code Refactoring Specialist"
version: "2026.1"
trigger_conditions:
- task_contains: ["refactor", "rewrite", "migrate", "optimize"]
- file_count_gt: 10
- complexity_score_gt: 7
intent_clarification:
required_fields:
- target_files
- desired_outcome
- acceptable_breakage: "Define what constitutes acceptable breakage (e.g., no more than 5% of tests fail)"
default_prompt: "Clarify the scope of this refactoring. Which files are off-limits?"
dependency_mapping:
max_depth: 5
detect_circular: true
prioritize_by: "criticality"
risk_assessment:
rules:
- "If dependency_depth > 3, flag as High Risk"
- "If ambiguity_index > 50, require secondary human review"
output_format:
plan_type: "mermaid"
include_alternatives: true
show_resource_estimates: true
Example Console Invocation
Once configured, invoking Fathom Flow is straightforward. Here are three common usage patterns:
Standard Invocation (Interactive)
fathom-flow analyze --profile default --query "Migrate the authentication module from JWT to OAuth2"
This launches an interactive session where the agent asks clarifying questions, builds the plan, and presents it for approval.
Batch Mode (Non-Interactive)
fathom-flow analyze --profile batch --query "Optimize all SQL queries in /src/db" --batch-approve
With Custom API Endpoint
For those integrating with OpenAI's ChatGPT API or Anthropic's Claude API:
fathom-flow analyze --api-endpoint https://api.openai.com/v1/chat/completions --api-key ${OPENAI_API_KEY} --query "Design a data pipeline for real-time analytics"
Emoji OS Compatibility Table
Fathom Flow's terminal output uses emoji for quick visual cues. Here is the compatibility matrix across operating systems:
| Operating System | Version | Emoji Support | Font Required | Notes |
|---|---|---|---|---|
| Windows 11 | 22H2+ | Full | Segoe UI Emoji | Works out of the box |
| Windows 10 | 1903+ | Full | Segoe UI Emoji | May need Windows Terminal |
| macOS Ventura | 13.0+ | Full | Apple Color Emoji | Native support |
| macOS Monterey | 12.0+ | Full | Apple Color Emoji | Native support |
| Ubuntu 22.04 | LTS | Partial | Noto Color Emoji | Install via sudo apt install fonts-noto-color-emoji |
| Ubuntu 20.04 | LTS | Partial | Noto Color Emoji | Requires manual font configuration |
| Fedora 38 | - | Partial | Noto Color Emoji | Similar to Ubuntu |
| Debian 12 | - | Partial | Noto Color Emoji | Similar to Ubuntu |
| CentOS 7 | - | Minimal | - | Consider using ASCII fallback |
| FreeBSD 13+ | - | Partial | Noto Color Emoji | Manual setup required |
Tip: If you see empty boxes instead of emoji, append --no-emoji to your invocation to fall back to ASCII indicators.
Feature Deep Dive
Intent Clarification Phase
The agent does not assume it understands your request. Instead, it generates a series of probing questions based on its internal ambiguity index. For instance, if you say "make the website faster," the agent might ask:
- "Define 'faster'—are we targeting Time to First Byte (TTFB) or Largest Contentful Paint (LCP)?"
- "What is the acceptable trade-off between performance and visual fidelity?"
- "Which user segments are most affected by the current slowness?"
This phase reduces rework by 47% in empirical tests (internal benchmarks, 2026).
Dependency Mapping
Fathom Flow builds a directed acyclic graph (DAG) of all required actions. It detects:
- Circular dependencies (e.g., Module A requires Module B, which requires Module A)
- Orphaned tasks (actions that do not contribute to the final goal)
- Resource bottlenecks (steps that require exclusive access to shared resources)
Risk & Ambiguity Flagging
Not all uncertainty is created equal. Fathom Flow distinguishes between:
- Known unknowns: "I know I need a database migration, but I don't know the exact schema changes yet."
- Unknown unknowns: "I didn't realize this legacy API call affects three downstream services."
The system tags each with a severity level and suggests mitigation strategies.
AI Integration: OpenAI & Claude APIs
Fathom Flow is API-agnostic by design. It can work with any LLM that accepts a structured prompt sequence. Here is how it integrates with the two dominant platforms:
OpenAI API (GPT-4, GPT-4 Turbo, GPT-4o)
import fathom_flow as ff
config = ff.Config(
api_type="openai",
model="gpt-4o",
temperature=0.3, # Lower temperature for more deterministic planning
planning_prompt_template="custom_templates/software_planning.txt"
)
plan = ff.PlanBuilder(config)
result = plan.analyze("Implement a rate limiter for the user API")
print(result.to_mermaid())
Anthropic Claude API (Claude 3 Opus, Claude 3.5 Sonnet)
import fathom_flow as ff
config = ff.Config(
api_type="anthropic",
model="claude-3-5-sonnet-20241022",
max_tokens_to_sample=4096,
use_extended_thinking=True # Leverage Claude's extended thinking for complex plans
)
plan = ff.PlanBuilder(config)
result = plan.analyze("Redesign the notification system to support real-time streaming")
result.export("notification_redesign_plan.json")
Hybrid Mode (Recommended)
For production use, Fathom Flow supports hybrid routing—sending simple tasks to cheaper models and escalating complex ones to premium models:
hybrid_routing:
thresholds:
low_complexity: { model: "gpt-4o-mini", max_tokens: 2000 }
medium_complexity: { model: "claude-3-haiku", max_tokens: 4000 }
high_complexity: { model: "claude-3-opus", max_tokens: 8000 }
Responsive UI & Multilingual Support
Responsive Web Dashboard
While Fathom Flow is primarily a CLI tool, it ships with a lightweight web dashboard for visual plan inspection. The dashboard is built with vanilla JavaScript and CSS, ensuring zero dependencies and fast load times. Key features:
- Responsive grid layout adapts from 320px mobile screens to 4K monitors
- Collapsible risk sections for deep diving into flagged issues
- Export to PDF for sharing plans with non-technical stakeholders
- Dark mode that respects your system preferences
Multilingual Plan Output
Fathom Flow can generate plan summaries in 12 languages, including:
| Language | Code | Support Level |
|---|---|---|
| English | en | Full |
| Chinese (Simplified) | zh-CN | Full |
| Spanish | es | Full |
| Japanese | ja | Full |
| German | de | Full |
| French | fr | Full |
| Portuguese | pt | Full |
| Korean | ko | Beta |
| Arabic | ar | Beta |
| Russian | ru | Beta |
| Hindi | hi | Alpha |
| Vietnamese | vi | Alpha |
To activate multilingual support, set the output_language field in your profile:
output_language: "ja" # Generates plan summaries in Japanese
24/7 Customer Support Philosophy
Fathom Flow does not offer "human support" in the traditional sense. Instead, it provides automated support loops that never sleep:
-
Self-diagnosis engine: If the plan generation fails, Fathom Flow attempts to identify the root cause (e.g., ambiguous query, missing API key, incompatible profile) and provides a corrective suggestion.
-
Community-powered FAQ: The built-in
--helpand--debugflags are augmented with a community-curated knowledge base. Runfathom-flow doctorto get context-specific troubleshooting. -
Continuous learning feedback: When a user rejects a plan, Fathom Flow logs the rejection reason (anonymized) and uses it to refine future plan generation. Over time, the system learns your preferences and becomes more aligned with your working style.
-
Emergency break-glass: If the system enters a loop or generates nonsensical plans, type
CTRL+Cto abort. Then runfathom-flow resetto restore factory defaults.
SEO-Friendly Ecosystem
Fathom Flow is built with discoverability in mind. The project's documentation follows SEO best practices:
- Schema markup for rich snippets in search results
- Structured headings (H1 -> H2 -> H3) for better readability and crawling
- Descriptive meta titles that include high-value keywords like "task previsualization," "AI planning tool," and "Claude Code helper"
- Internal linking between related documentation pages
The keywords naturally integrated into this README include: task previsualization, AI agent planning, Claude Code assistant, OpenAI integration, task complexity analysis, dependency mapping tool, AI workflow orchestration, software project precompilation, cognitive load estimation, intent clarification system.
MIT License
This project is licensed under the MIT License. You are free to use, copy, modify, merge, publish, distribute, sublicense, and sell copies of the software, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
See the full text of the MIT License for details.
Disclaimer
Fathom Flow is an open-source tool for augmenting AI agent behavior. It is not a replacement for human judgment, nor is it a guarantee of task correctness.
- The risk assessments generated by Fathom Flow are probabilistic, not deterministic. Always review plans before approving execution.
- Fathom Flow does not modify the underlying AI model. It only influences the prompt sequence. The final output quality depends on the model's training and capabilities.
- The "24/7 support" described above refers to automated systems, not human customer service agents. Do not rely on Fathom Flow for time-critical production support.
- The multilingual support is community-maintained. Translation quality may vary, especially for languages marked as "Alpha" or "Beta."
- By using Fathom Flow, you acknowledge that the developers are not liable for any damages arising from its use, including but not limited to incorrect task execution, data loss, or opportunity cost.
This project is not affiliated with Anthropic (Claude) or OpenAI (ChatGPT). All trademarks belong to their respective owners.
Built with clarity in mind. Version 2026.1. Last updated March 2026.