{"id":"c32ee437-06f1-42bc-bce8-ff259492e708","slug":"goflow-agent","kind":"skill","name":"GoFlow-Agent","summary":"AI Agent","owner":"FyMatt","repoUrl":"https://github.com/FyMatt/GoFlow-Agent","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":3,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-04-26T23:31:24.000Z","addedAt":"2026-10-21T17:17:01.706Z","logoUrl":"https://avatars.githubusercontent.com/u/77987934?u=ee03c03d3b9f8fe89c89b3996fcec35efda6d333&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["writing"],"tags":[],"runtime":"go","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-22T13:03:03.391Z","sample":false,"url":"https://conduits.dev/tools/goflow-agent","language":"Go","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# GoFlow Agent\n\n[English](./README.md) | [简体中文](./README.zh-CN.md)\n\nA local agent runtime in Go for building domain-specific agents with multi-agent workflows, MCP tools, dynamic skills, workspace-scoped session state, and an optional HTTP/SSE surface.\n\n## What it is\n\nGoFlow Agent separates the **runtime home** from the **workspace root** so you can run the framework from its own repo while pointing it at any target folder.\n\nThat makes it useful for:\n- project bootstrapping in an empty directory\n- documentation generation\n- tool-augmented agent workflows\n- building specialized agents by adding skills and MCP tools\n- exposing the same runtime through CLI or HTTP\n\nPackaged examples:\n\n- [examples](./examples): overview of copyable extension examples.\n- [examples/extension-workflow](./examples/extension-workflow): a compact\n  extension that combines a Python MCP server, a custom read-only agent, a\n  skill, and a graph workflow. Smoke-test it with\n  `python scripts/validate_extension_workflow.py`.\n- [examples/binary-analysis-kit](./examples/binary-analysis-kit): a fuller\n  materialized kit that connects an Agent, Skill, containerized MCP helper,\n  Workflow, Workflow Template, Team Template, and Policy Rule for binary\n  triage. Validate it with `python scripts/validate_binary_analysis_kit.py`.\n\nDeployment files can be checked locally without Docker using `python scripts/validate_deployment_assets.py`.\n\nFor end-user installation and deployment commands, see [Installation And Deployment](./docs/install.md). For Chinese instructions, see [安装与部署](./docs/install.zh-CN.md).\n\n## Key features\n\n- Multi-agent runtime with named agent profiles\n- Modular resource storage for agents, providers, MCP servers, skills,\n  workflows, workflow templates, team templates, policy rules, and kits\n- Registry-backed built-in workflows and file-backed workflow templates plus\n  runtime-home custom workflow graphs\n- Branded CLI startup banner with runtime/workspace summary\n- Best-effort terminal title updates in interactive CLI sessions\n- Blocking workflow approvals with arrow-key + Enter selection and numeric fallback\n- OpenAI-compatible provider integration with fallback support\n- stdio-based MCP tool execution\n- Cross-language MCP support with built-in Go and Python servers\n- Dynamic skill loading from `SKILL.md`\n- Complex skills can declare deterministic helper scripts that execute through\n  `skill_runner/run_script` as normal approved/audited `exec` tools\n- Durable ordinary Agent runs and Workflow runs with reconnectable event\n  streams, replay, diffs, export, explicit cancel/retry, and run-scoped\n  approvals\n- Workflow Studio canvas labels control-node branches, loop bodies, and\n  post-control paths, with hover/selection scope frames for ordinary users\n- Per-workspace session persistence with a lightweight `session.json` index and\n  complete compressed `session.full.json.gz` replay archive\n- Workspace confirmation gate: pure chat can run from the default directory, while file reads/writes, `@file` references, command execution, and workflows require a confirmed workspace\n- Audit logging and CLI trace/status/session output\n- External workspace mode via `--workspace`\n- Windows, Linux, and Docker deployment paths\n- Docker/Podman is the recommended strong isolation path for generated,\n  third-party, write, exec, and network MCP tools\n- HTTP JSON API and SSE streaming via `--http`\n\n## Built-in Domain Resources\n\nGoFlow ships with linked starter resources for common vertical domains:\n\n- Agents: `software-engineer`, `security-researcher`,\n  `web-security-researcher`, `binary-analyst`, `documentation-specialist`,\n  `operations-specialist`, `support-specialist`, and\n  `framework-extension-architect`\n- Skills: `execution-plan`, `code-writing`, `code-audit`,\n  `vulnerability-research`, `web-vulnerability-research`,\n  `binary-vulnerability-research`, and `reverse-engineering`\n- Kit presets: `multi-domain-agent`, `software-engineering`,\n  `agent-framework`, `web-security`, `security-research`, `binary-analysis`,\n  `documentation`, `operations-runbook`, and `customer-support`\n- Workflow templates and team templates for those domains, including\n  `multi-domain-intake-router` as the recommended first-run path. Built-in\n  workflow templates are embedded from `internal/agent/templates/workflows/*.yaml`\n  and can be overridden from `templates/workflows/*.yaml`.\n\nUse `/kits multi-domain-agent-kit` or `/workflow-templates\nmulti-domain-intake-router` to inspect how Agent, Skill, Tool, Team, Workflow\nTemplate, Policy Rule, and Kit resources connect.\n\nRecommended first-run paths:\n\n| Goal | Start from | What it gives you |\n| --- | --- | --- |\n| General onboarding | `multi-domain-agent-kit` | linked agents, skills, tools, teams, policy gates, and the `multi-domain-intake-router` workflow template |\n| Software changes | `software-engineering-kit` | planner/fixer/auditor style implementation workflow with review gates |\n| Web security review | `web-security-kit` | page and client-asset collection plus evidence-based security review |\n| Binary triage | `binary-analysis-kit` | static binary metadata, strings, hex preview, team review, and report handoff |\n| Operations and network-device planning | `operations-runbook-kit` | runbook drafting plus authorized device discovery, command, dry-run, rollback, and audit evidence contracts |\n| Framework extension | `agent-framework-kit` | starter resources for creating new Agent, Skill, Tool, Workflow, Team, Policy, and Kit packages |\n\n## Quick start\n\n### Prerequisites\n\n- Go 1.25+\n- Python 3 on `PATH` if you want the `python_notes` MCP server\n- Docker or Podman if you want the recommended container sandbox for risky MCP\n  tools\n- An OpenAI-compatible model endpoint for actual Agent runs\n- Provider credentials and model settings, configured either in Web Studio,\n  `configs/providers/*.yaml`, or environment variables\n\n### Configure a model provider\n\nGoFlow can start before a model provider is fully configured. This lets new\nusers open Web Studio, inspect diagnostics, and fill Provider settings from the\nResources or Settings pages. Agent runs will return a setup-required message\nuntil `base_url`, `api_key`, and `model` are configured.\n\nEnvironment variables remain supported:\n\n```bash\nexport GOFLOW_BASE_URL=http://localhost:11434/v1\nexport GOFLOW_API_KEY=local-dev-key\nexport GOFLOW_MODEL=qwen2.5-coder:7b\nexport GOFLOW_BACKUP_BASE_URL=$GOFLOW_BASE_URL\nexport GOFLOW_BACKUP_API_KEY=$GOFLOW_API_KEY\nexport GOFLOW_BACKUP_MODEL=$GOFLOW_MODEL\n```\n\nFor a ready-to-edit template, copy `.env.example` and fill in your own values.\nIf you save a Provider from Web Studio with a literal API key, GoFlow writes it\nto `configs/providers/<name>.yaml` as plain text. For release branches or shared\nrepos, keep the committed Provider file using `${GOFLOW_API_KEY}` and supply\nthe real value through `.env`, your shell, or another local secret store.\n\nOn Windows, use the bootstrap script. You can set a key first or configure the\nProvider later from Web Studio settings:\n\n```bat\nset GOFLOW_API_KEY=your-deepseek-key\nrun-goflow.example.cmd\n```\n\nThe script starts HTTP/Web Studio at `http://127.0.0.1:8080/console`. Pass a\nworkspace path as the first argument when you want to work on another project,\nfor example `run-goflow.example.cmd D:\\Projects\\my-workspace`. To use the CLI\ninstead, run `go run ./cmd/goflow` from source or `bin\\goflow.exe` from a\nrelease archive.\n\nThe bootstrap script fills in DeepSeek defaults without embedding credentials in the repo.\n\n### Start the CLI\n\nUse the current directory as the workspace:\n\n```bash\ngo run ./cmd/goflow\n```\n\nWhen no `--workspace` is provided, the CLI treats the current directory as a default workspace candidate. Pure chat can continue immediately. Before any workspace-scoped action such as reading files, writing files, running commands, attaching `@file` references, generating project files, or running workflows, GoFlow asks you to confirm that default with:\n\n```text\n/workspace confirm\n```\n\nUse an external directory as the workspace:\n\n```bash\ngo run ./cmd/goflow --workspace D:/my-empty-project\n```\n\nAt startup the interactive CLI now prints a compact branded banner with runtime/workspace paths plus the currently active agent, current mode, tool policy, allowed tool kinds, explicitly allowed tool names, workflow summary, pending conversational handoff summary, pending approval count, and any remembered per-workspace tool approvals. It also sets the terminal title to `GoFlow Agent - <workspace>` when the terminal supports OSC title updates.\n\nThe `/agents` command surfaces each configured agent profile with its mode, tool policy, allowed tool kinds, and `allowed_tools` allowlist so operators can see why a given tool call is or is not permitted before switching agents.\n\nHTTP server mode keeps the plain startup line and does not use the interactive banner.\n\n### Start the HTTP API\n\n```bash\ngo run ./cmd/goflow --http :8080\n```\n\nOr combine it with an external workspace:\n\n```bash\ngo run ./cmd/goflow --workspace D:/my-empty-project --http :8080\n```\n\nAt startup the server prints runtime, workspace, and listen address:\n\n```text\nGoFlow HTTP API ready. runtime=C:\\path\\to\\agent workspace=D:\\my-empty-project addr=:8080\n```\n\nUse `Ctrl+C` to stop HTTP mode. GoFlow shuts the server down gracefully and saves\nthe session snapshot before exiting.\n\n### Use Web Studio\n\nOpen `http://127.0.0.1:8080/console` after starting HTTP mode.\nUse `?lang=zh` or `?lang=en` when you want a shareable language-specific link,\nfor example `http://127.0.0.1:8080/console?lang=zh#workspace`.\n\nFor the lowest-friction path:\n\n1. Open **Resources**.\n2. Choose the `multi-domain-agent` starter kit.\n3. Use **Create linked starter** to materialize its Agent, Skill, Tool,\n   Workflow, Workflow Template, Team Template, Policy Rule, and Kit files.\n4. Open **Workflow Studio**.\n5. Start from `multi-domain-intake-router`, inspect the template cards for node\n   mix and linked resources, then run or fork the graph.\n\nWorkflow Studio exposes node metadata, examples, input/output references,\napproval gates, quality gates, and template composition so users do not need to\nguess which fields are valid before editing YAML.\n\nWorkflow Studio opens in **Simple** mode by default for ordinary users. Simple\nmode keeps the canvas, templates, task cards, resource pickers, and visual flow\ncontrols visible while hiding raw maps, context contracts, execution-order\ninternals, and run debugging. Turn on **Expert** mode when you want the complete\ndeveloper surface: all node types, all inspector tabs, raw params, advanced\nrouting, context contracts, input/output maps, and run diagnostics. Both modes\nsave the same workflow schema.\n\nThe **Observability** page shows live runtime health, current run focus, model\ncost diagnostics, and MCP tool pressure. Use the MCP pressure panel to spot\nactive tool calls, queued calls, and saturated tool servers before increasing a\nworkflow's concurrency or retrying a stalled run.\n\nIf you are unsure how to configure a node in Studio, or what to put in\n`input`, `outputs`, `artifacts`, or `acceptance_criteria`, go straight to\n[Workflow Graphs](./docs/workflows.md), especially the node quick reference,\nStudio panel guide, and node-type usage sections.\n\nIf you are unsure how Agents, Skills, Tools, Workflows, Team Templates, Policy\nRules, and Kits differ or connect, use the\n[Resources And Settings Guide](./docs/resources.md).\n\n### Run with Docker\n\nFor local source checkouts, copy `.env.example` to `.env`, fill in provider values, then run:\n\n```bash\ndocker compose up --build\n```\n\nThe container listens on `http://127.0.0.1:8080` and uses `./workspace` as `/workspace` inside the container. See [Deployment](./docs/deployment.md) for Windows, Linux, and Docker details.\n\nTo run a published image instead of building locally:\n\n```bash\ndocker run --rm -it \\\n  --env-file .env \\\n  -p 8080:8080 \\\n  -v \"$PWD/workspace:/workspace\" \\\n  ghcr.io/fymatt/goflow-agent:<version>\n```\n\nRelease archives and Docker images are covered in [Installation And Deployment](./docs/install.md).\nContainerized Python MCP tool presets use the companion\n`ghcr.io/fymatt/goflow-agent-mcp-python:<version>` image by default.\n\n## Current status\n\nThe current baseline is usable end to end through CLI and Web Studio: resource\nmanagement, MCP tools, skills, workflows, durable ordinary Agent runs, durable\nWorkflow runs, approvals, workspace lifecycle, cost diagnostics, Docker-first\nisolation, and CI/release packaging are implemented. Built-in resources now\ninclude connected multi-domain Agent, Skill, Tool, Team, Workflow Template,\nPolicy Rule, and Kit packages. Ongoing work should be driven by real deployment\nfeedback, additional domain templates, and measurement-based cost and sandbox\nhardening rather than by missing core runtime pieces.\n\n## Common CLI commands\n\nCLI commands use the `/` prefix.\n\n```text\n/help\n/skills\n/tools\n/agents\n/teams [name]\n/team-state [run-id] [team]\n/use <agent>\n/mode <chat|plan|audit|fix>\n/workspace [status|confirm|clear|use <path>]\n/workflow plan-fix-audit [--approve] <request>\n/workflow skill-chain <request>\n/workflow <custom-name> <request>\n/workflow-templates [name]\n/workflow-node-metadata [type]\n/expression-helpers [name] [--mode <mode>] [--node-type <type>]\n/workflow-schemas [name] [--rebuild|--json|--export|--import <path>|--clear]\n/status\n/cost\n/config-diagnostics [--json]\n/session\n/trace on|off\n/approve <tool-call-id>\n/deny <tool-call-id>\n/reload\n/reload-tools\n/skill-templates\n/new-skill <template> <name>\n/new-tool python <name>\n/new-agent <name>\n/new-provider <name>\n/new-workflow <name> [--template <template>]\n/kits [name] [--export]\n/kits --import <path> [--replace]\n/new-kit <preset> <name> [--materialize|--full]\nexit\n```\n\n`/workspace status` shows whether the active workspace is explicit or still the current-directory default. `/workspace confirm` enables workspace-scoped tools for the current session. `/workspace clear` removes that confirmation. `/workspace use <path>` dynamically rebinds the CLI to another workspace when the runtime is idle. The old workspace session is saved, old MCP child processes are closed, and a fresh workspace-scoped runtime/session/tool policy is loaded. If a tool approval, handoff, workflow pause, or durable run is still active, the command blocks the switch and prints a restart fallback.\n\n`--approve` pre-approves the planner -> fixer stage transition. Without it, GoFlow first asks whether to enter the fixer stage, then separately prompts again if a fixer tool call requires confirmation.\n\n`/new-workflow <name> [--template <template>]` creates `workflows/<name>/workflow.yaml`. The default template is `plan-fix-audit`; richer built-ins include `complex-project-delivery`, `engineering-parallel-delivery`, `plan-implement-audit`, `agent-framework-extension`, `software-quality-gate`, `web-research-risk`, `security-audit-evidence-gate`, `parallel-research-review`, `binary-triage`, `docs-review-publish`, `operations-runbook`, `customer-support-triage`, `human-input-security-review`, and `software-team-review-gate`. That file is executable through `/workflow <name> <request>` and can declare named stages with `agent`, `skill`, stage-level `model` routes, explicit `input`/`outputs`, replay `artifacts`, control nodes such as `condition`, `policy_guard`, `quality_gate`, `parallel`/`join`, `for_each`, `loop`, and `sub_workflow`, approval gates, and `next` edges.\n\nShipped workflow templates are held to a delivery quality bar: each built-in\ntemplate validates as a graph, includes an explicit end node, emits replayable\nreport/evidence artifacts, declares acceptance criteria, uses a quality or\npolicy gate, and finishes with a user-facing report, handoff, publish summary,\nor materialized workflow draft. Shipped team templates likewise declare role\nresponsibilities, handoffs, shared blackboard references, quorum presets where\nneeded, and output contracts.\n\nUse `complex-project-delivery` for broad implementation work that should keep running until the accepted plan is complete: it analyzes requirements, builds a user-confirmed project plan, iterates implementation with verification and review, updates plan state, runs final validation, and emits a completion report. Use `engineering-parallel-delivery` when a complex task should be decomposed by a strong planning route, executed as bounded parallel worker slices on cheaper routes, then aggregated, audited, and resolved if needed without copying full history into every worker. Use `plan-implement-audit` for one bounded task that still needs planning, implementation, verification, audit, a quality gate, and a final report.\n\n`plan-fix-audit` and `skill-chain` remain runnable compatibility executors.\nCustom graph files are the editable model. In HTTP, `/api/workflow-graphs`\nlists editable graph files, while `/api/workflow-options.workflow_executors`\nlists every runnable workflow entry for run selectors. Saving a valid graph\nwith the same name as a compatibility executor overrides that executor.\n\n`/workflow-templates`, `/workflow-node-metadata`, and `/expression-helpers`\nexpose the workflow authoring catalog from the terminal. They mirror the\nStudio-facing workflow template, node metadata, and expression helper APIs so\nCLI users can inspect available node types, editable fields, outputs, helper\nsignatures, examples, and custom metadata paths without opening the browser.\nBuilt-in workflow node metadata is embedded from\n`internal/agent/templates/workflow_nodes/*.yaml`.\nBuilt-in expression helper metadata is embedded from\n`internal/agent/templates/expression_helpers/*.yaml`, with runtime overrides\navailable under `metadata/expression_helpers/*.yaml` and related template paths.\nBuilt-in workflow policy rule metadata is embedded from\n`internal/agent/templates/policy_rules/*.yaml`; custom executable rules still\nlive under `policies/workflow_rules/*.yaml`.\n\n`/kits` lists local vertical Agent packages from `kits/<name>/kit.yaml`, and `/kits <name>` shows one manifest's referenced providers, agents, skills, tools, workflows, teams, policies, examples, metadata, and environment warnings. `/kits <name> --export [--format json|yaml] [--include-secrets]` prints a portable kit bundle, and `/kits --import <path> [--replace]` imports one into the current runtime home. `/new-kit <preset> <name>` creates a starter kit manifest; add `--materialize` or `--full` to generate a linked starter bundle with its own agent, skill, Docker/Podman containerized MCP helper, workflow, workflow template, team template, policy rule, and kit manifest. Built-in presets include `multi-domain-agent`, `software-engineering`, `agent-framework`, `web-security`, `security-research`, `binary-analysis`, `documentation`, `operations-runbook`, and `customer-support`. The manifest stays versionable and can later be validated, edited, exported, or imported through Studio resource APIs.\n\nWhen `binary-analysis` is materialized, the generated helper is a static binary\ntriage MCP server with `binary_file_info`, `binary_strings`, and `hex_preview`.\nUse ordinary paths such as `sample.bin` for binary inputs; `@file` references\nare reserved for UTF-8 text content. That helper is template-backed as well:\nthe embedded template is\n`internal/scaffold/templates/tools/python/binary-analysis-server.py.tmpl`, with\nruntime overrides at\n`templates/tools/python/binary-analysis-server.py.tmpl`.\n\nTool scaffold presets are file-backed. Built-ins are embedded from\n`internal/scaffold/templates/tools/scaffolds/presets.yaml`; a runtime can add or\noverride presets with YAML files under `templates/tools/scaffolds/*.yaml`.\nThe generated Python MCP tool server and its modular MCP config are\nfile-backed too: built-ins live under\n`internal/scaffold/templates/tools/python/server.py.tmpl` and\n`internal/scaffold/templates/tools/python/config.yaml.tmpl`, with runtime\noverrides at `templates/tools/python/server.py.tmpl` and\n`templates/tools/python/config.yaml.tmpl`. `/new-tool python` and Studio's\ndefault Python tool resource use the same renderer.\n\nKit scaffold presets are file-backed. Built-ins are embedded from\n`internal/scaffold/templates/kits/scaffolds/presets.yaml`, and a runtime can add\nor override presets with YAML files under `templates/kits/scaffolds/*.yaml`.\nMaterialized kit resources are file-backed too: the default `kit.yaml`,\n`agent.yaml`, `SKILL.md`, container MCP config, workflow, workflow template,\nteam template, policy rule, and workflow note templates are embedded from\n`internal/scaffold/templates/kits/materialized/generic/*.tmpl`. Override them\nper preset with `templates/kits/materialized/<preset>/*.tmpl`, or override the\ngeneric fallback with `templates/kits/materialized/generic/*.tmpl`.\n\nTeam templates are file-backed as well. Built-ins are embedded from\n`internal/agent/templates/teams/*.yaml`; runtime homes can add new reusable\nteams or override shipped teams with `templates/teams/*.yaml`. The same catalog\nis used by `/teams`, workflow `team` node validation, Kit materialization, and\nStudio resource forms.\n\n`/workflow-schemas` lists observed workflow output schemas captured from\ncompleted runs. `/workflow-schemas <name>` shows stage output fields and types,\n`--json` prints the list or detail as JSON for scripts, `--export` prints a\nversioned bundle compatible with the HTTP import API, `--import <path>` imports\nthat bundle or a raw schema JSON file, `--rebuild` rebuilds the catalog from\nretained run history, and `--clear` removes one schema or all schemas. The same\ncatalog powers Studio expression suggestions and reusable schema resources under\n`schemas/workflows/*.json`. That directory is optional and normally starts\nempty; built-in workflow templates are embedded separately from\n`internal/agent/templates/workflows/*.yaml`.\n\nCustom `policy_guard` rules can be stored as YAML under `policies/workflow_rules/*.yaml`; they appear in `/api/workflow-options` alongside built-in guard rules for Studio forms and workflow execution. Policy rule scaffold presets are also YAML-backed: built-ins live in `internal/scaffold/templates/policies/scaffolds/presets.yaml`, and runtime homes can add or override presets with `templates/policies/scaffolds/*.yaml`.\n\n`/new-agent <name>`, `/new-provider <name>`, and the Studio tool builder create modular runtime config files under `configs/agents/`, `configs/providers/`, and `configs/mcp_servers/`. These files are loaded on startup, so custom agents, model providers, and MCP servers can stay versionable without bloating the main `configs/goflow.yaml`. The default Agent and Provider scaffolds are file-backed too: built-ins live under `internal/scaffold/templates/config/agents/default.yaml.tmpl` and `internal/scaffold/templates/config/providers/default.yaml.tmpl`, and runtime homes can override them with `templates/config/agents/default.yaml.tmpl` and `templates/config/providers/default.yaml.tmpl`.\n\n`/skill-templates` and `/new-skill <template> <name>` use file-backed Skill scaffold templates. Built-ins are embedded from `internal/scaffold/templates/skills/scaffolds/templates.yaml`, and runtime homes can add or override templates with `templates/skills/scaffolds/*.yaml`.\n\n`/new-team <preset> <name>` and `/api/resources/team-templates/scaffolds` use file-backed Team scaffold presets. Built-ins are embedded from `internal/scaffold/templates/teams/scaffolds/presets.yaml`, with runtime overrides in `templates/teams/scaffolds/*.yaml`.\n\nRunning `/workflow` without arguments prints usage plus discovered custom workflows.\n\n`/cost` shows the session's prompt budget and token usage history, including\naverage/max estimated prompt size, cacheable/non-cacheable context, top agents,\nprovider-reported token totals, cached-token hit rate, prompt-prefix reuse, and\noptimization hints. It uses already-recorded runtime diagnostics and does not\ncall the model.\n\n`/config-diagnostics` reload-validates the saved `configs/goflow.yaml` plus\nmodular agent/provider/MCP/workflow resource files, summarizes warnings/errors,\nand hides optional empty extension directories from the primary text list.\nUse `/config-diagnostics --json` for the full machine-readable envelope that\nmatches `GET /api/config/diagnostics`. HTTP clients can request\n`/api/config/diagnostics?include_optional=0` to hide optional non-actionable\ninfo items in JSON responses.\n\n## Workflow approvals\n\nWhen `/workflow plan-fix-audit ...` pauses, the CLI can stop at two different approval boundaries:\n- stage approval before entering the fixer stage\n- tool approval for a suspended fixer tool call\n\nBoth approval steps are blocking. If both happen in one workflow run, GoFlow stays inside the approval flow until each decision is resolved.\n\nIf the operator chooses the workflow-level \"approve all pending tool calls\" path, later matching tool calls in the same workflow run stay auto-approved only within the same workflow/stage/tool scope. The scope does not leak across different workflows, stages, or tools.\n\nIn interactive terminals, the prompt uses an arrow-key selector:\n- `Up` / `Down` move between approval actions\n- `Enter` confirms the highlighted action\n- `1`, `2`, and `3` still work as direct shortcuts\n\nAvailable choices:\n- approve the current tool call\n- deny the current tool call\n- approve all currently pending tool calls for this workflow run\n\nWhen stdin/stdout are not interactive terminals, GoFlow falls back to the numeric `1/2/3` prompt so redirected sessions and simpler terminals still work.\n\nWhile the workflow is paused:\n- `/status` highlights the current workflow state, next stage, and each pending approval with tool, agent, stage, and argument summary\n- `/session` shows structured `Workflow` and `Pending approvals` sections from the persisted session snapshot\n- the latest workflow snapshot stores the current request, summary, next stage, and latest approval prompt/result\n\nThe current workflow state and pending approvals are also persisted into the session snapshot so operator-facing workflow state survives normal CLI inspection.\n\nWhen a suspended fixer tool call is approved and the workflow resumes, GoFlow now replays the original suspended assistant/tool-call context together with the approved tool result back into the fixer conversation loop instead of restarting from a fresh prompt.\n\n## Ordinary chat routing and plan confirmation\n\nThe shipped config now starts ordinary CLI sessions on the default `chat` agent instead of dropping directly into `planner` mode.\n\nFor plain-language requests, the runtime can reroute into planner/fixer/auditor roles when the request clearly asks for planning, implementation, or review. The runtime remains the final authority: workflow state, pending approvals, and other lifecycle constraints can still prevent an unsafe switch.\n\nIf ordinary chat first produces a plan and is waiting for approval to execute it, GoFlow records a pending conversational handoff in the session snapshot. Natural replies such as `可以`, `继续`, `就按这个执行`, `全部添加`, `yes`, or `go ahead` confirm the handoff, switch to the target executable agent, and continue from the approved plan instead of looping back into more planner output.\n\nEsc cancellation is different from a pending handoff. Pressing Esc twice cancels\nthe active turn; a later standalone `继续`, `重试`, or `continue` re-runs the\ncancelled request from the beginning with a clear retry log.\n\nWhile that handoff is pending:\n- the startup banner can show a pending handoff summary on restart\n- `/session` includes a structured `Pending handoff` section\n- normal write-capable work still follows the usual tool approval flow once execution begins\n\n## HTTP API\n\nSession persistence is split for Web Studio performance: `.goflow/session.json`\nis a compact index for status polling, while `.goflow/session.full.json.gz`\nstores the complete compressed run history used for detailed replay.\n\nCurrent endpoints:\n- `GET /api/runtime`\n- `GET /api/runtime/cost`\n- `GET /api/help`\n- `GET /api/workspace`\n- `POST /api/workspace/confirm`\n- `POST /api/workspace/clear`\n- `POST /api/workspace/select`\n- `POST /api/run`\n- `POST /api/run/stream`\n- `GET /api/runs`\n- `GET /api/session`\n- `GET /api/session-artifacts`\n- `GET /api/session-artifacts/{id}`\n- `POST /api/workflows/{name}`\n- `POST /api/workflows/{name}/stream`\n- `GET /api/workflow-runs`\n- `GET /api/workflow-runs/{id}`\n- `GET /api/workflow-runs/{id}/actions`\n- `GET /api/workflow-runs/{id}/replay`\n- `POST /api/workflow-runs/{id}/approve`\n- `POST /api/workflow-runs/{id}/approve/stream`\n- `POST /api/workflow-runs/{id}/approve-tools`\n- `POST /api/workflow-runs/{id}/approve-tools/stream`\n- `GET /api/workflow-graphs`\n- `POST /api/workflow-graphs`\n- `POST /api/workflow-graphs/validate`\n- `POST /api/workflow-graphs/import`\n- `GET /api/workflow-graphs/{name}`\n- `PUT /api/workflow-graphs/{name}`\n- `DELETE /api/workflow-graphs/{name}`\n- `GET /api/workflow-graphs/{name}/export`\n- `POST /api/workflow-graphs/{name}/validate`\n- `GET /api/workflow-options`\n- `GET /api/workflow-templates`\n- `GET /api/workflow-templates/{name}`\n- `GET /api/team-templates`\n- `GET /api/team-templates/{name}`\n- `GET /api/team-state`\n- `GET /api/resources/skills`, `GET/PUT /api/resources/skills/{name}`\n- `GET/PUT/DELETE /api/resources/skills/{name}/files/...`\n- `GET /api/resources/agents`, `GET/PUT/DELETE /api/resources/agents/{name}`\n- `GET /api/resources/providers`, `GET/PUT/DELETE /api/resources/providers/{name}`\n- `GET /api/resources/tools`, `GET/PUT/DELETE /api/resources/tools/{name}`\n- `GET /api/resources/policy-rules`, `GET/PUT/DELETE /api/resources/policy-rules/{name}`\n- `GET /api/resources/team-templates`, `GET/PUT/DELETE /api/resources/team-templates/{name}`\n- `POST /api/approvals/{callID}/approve`\n- `POST /api/approvals/{callID}/approve/stream`\n- `POST /api/approvals/{callID}/deny`\n- `POST /api/approvals/{callID}/deny/stream`\n- `POST /api/approvals/approve-all`\n\nHTTP mode also serves a basic workspace page at `GET /workspace`. It shows the\ncurrent workspace root, whether it is confirmed, and actions for confirm, clear,\nor selecting another path. Packaged HTTP mode supports dynamic workspace rebind\nwhen execution is idle; fallback responses include explicit restart guidance and\nblocker codes so browser clients can explain why a switch is unavailable.\n\n`GET /api/runtime` includes a `cost` block with the latest prompt budget,\nbounded prompt-budget history, average/max estimated input size, cacheable\nprefix average, non-cacheable context average, prompt-prefix hash counts, stored\ntoken usage samples, per-agent/per-mode/per-stage trend rows, and compact\nrecommendations for likely avoidable context in Studio cost diagnostics.\nRecommendations include machine-readable `measurement`, `action`,\n`requires_config`, and `expected_savings_kind` fields so Studio can distinguish\nobserved waste from optional configuration changes such as low-cost router or\nsummarizer routes.\n`GET /api/runtime/cost` returns the same cost block alone for lightweight\npolling.\nLarge compacted tool observations are stored as session artifacts with refs like\n`goflow://session-artifacts/<id>`; include that ref in a later CLI/HTTP request\nto rehydrate the artifact content into prompt context only when needed.\nThe same endpoint includes a `verifier` block showing the effective verifier\nagent/provider/model route, so deployments can send low-risk post-run checks to\na cheaper model without changing the main fixer or auditor profile.\nOptional `cost_control.router` and `cost_control.summarizer` routes are exposed\nas `auxiliary_models`; they can move unmatched intent classification and\niteration-budget final summaries to cheaper configured providers.\n\n### Example: final JSON response\n\n```bash\ncurl -s -X POST http://127.0.0.1:8080/api/run \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"input\":\"summarize this workspace\"}'\n```\n\n### Example: SSE stream\n\n```bash\ncurl -N -X POST http://127.0.0.1:8080/api/run/stream \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"input\":\"hello\"}'\n```\n\nThe SSE endpoint forwards runtime `schema.StreamEvent` values directly, using the event type as the SSE `event:` field and the JSON-encoded event as the `data:` field.\n\nSSE clients should handle these event types:\n\n- `text`, `status`, `done`, and `final_message` for model output and turn completion\n- `task_stage` for high-level stage changes such as inspect, plan, modify, verify, and summarize\n- `tool_call`, `tool_result`, and `approval` for tool execution and confirmation pauses\n- `prompt_budget` for pre-call estimated prompt cost by system prompt, compacted session history, messages, tool schemas, matched skill, filtered tool count, and stable prompt-prefix/cache diagnostics\n- `token_usage` for provider-reported prompt/output/cache token counts\n- `workflow_result` for final or paused workflow state from `/api/workflows/{name}/stream` and streamed approval resumes\n\nThe streamed approval endpoints resume ordinary chat or workflow execution when the approved or denied call has resumable context.\n\nHTTP mode also serves the embedded Agent Studio at `GET /console` and\n`GET /workflows`. The Studio is a modern visual workflow surface with a\nworkflow list, node palette, draggable stage canvas, property panel, run\npreview, approvals, resource catalog, workspace controls, observability, and\nsettings/update guidance. The workflow APIs expose reusable graph templates\nand multi-agent team templates for Studio scaffolding. The Playground can choose a specific agent before a\nrun, the resource catalog includes a validated Skill editor, and the main UI supports English and Chinese. Custom workflow graphs are persisted under\n`workflows/<name>/workflow.yaml`. See [Workflow Graphs](./docs/workflows.md).\n\nThe Settings page shows the release update strategy without contacting GitHub\nautomatically. Users explicitly click the update check button, which calls\n`POST /api/update-policy/check` and compares the running build with the\nconfigured release feed.\n## Built-in MCP tools\n\n- `file_tools/list_dir`\n- `file_tools/list_tree`\n- `file_tools/file_info`\n- `file_tools/read_file`\n- `file_tools/search_files`\n- `file_tools/write_file`\n- `file_tools/delete_file`\n- `web_tools/web_search`\n- `web_tools/fetch_url`\n- `web_tools/fetch_page_assets`\n- `web_tools/browser_snapshot`\n- `web_tools/browser_probe_points`\n- `network_tools/device_discovery_plan`\n- `network_tools/device_command_plan`\n- `network_tools/device_config_dry_run`\n- `python_notes/read_note`\n- `python_notes/write_note`\n- `python_notes/python_ast_summary`\n- `python_notes/json_query`\n- `python_notes/binary_file_info`\n- `python_notes/binary_strings`\n- `python_notes/hex_preview`\n\nFile, note, source-inspection, and binary-inspection tools resolve every path under the active workspace root and reject path traversal or symlink escapes. Text file reads are decoded as UTF-8, UTF-8 BOM is accepted and stripped, and non-UTF-8 bytes are rejected for text tools so binary inspection tools can handle them instead. If the workspace was only defaulted from the current directory, GoFlow hides workspace-scoped read/write/exec tools from the model until you confirm it. Write operations render git-like CLI summaries with status letters, added/deleted line counts, changed line ranges, byte counts, and compact colored diff hunks. In the interactive CLI, type `@` to show workspace file suggestions, then type a prefix and press `Tab` to complete a unique match or show candidates. Workspace file suggestions skip dependency/build directories such as `.venv`, `node_modules`, `.git`, `__pycache__`, `vendor`, `dist`, and `build` before result limits are applied, and filename fragments work as contains searches. You can reference workspace files inline with `@relative/path.ext`; GoFlow reads the file through the normal `file_tools/read_file` path, prints the same tool logs, and attaches the file content before the request reaches the agent. In non-interactive input, type `@prefix` as a full line to list matching references.\n\nWorkspace switching is intentionally conservative. The CLI `/workspace use\n<path>` and packaged HTTP `/api/workspace/select` can dynamically rebind only\nwhile execution is idle. `/api/workspace` and `/api/runtime` expose\n`switch_mode`, blockers, action hints, and restart guidance so clients can show a\nfolder picker, submit the selected path, and explain when a restart is safer.\n\nInteractive CLI input also supports `Tab` completion for `/` commands and consumes arrow/Home/End/Delete key sequences so those keys do not appear as literal escape text in ordinary prompts.\n\n## Example use cases\n\n### Inspect a project\n\n```text\nPlease read the README and summarize the current project structure.\n```\n\n### Run the staged workflow\n\n```text\n/workflow plan-fix-audit improve workflow error handling\n```\n\n### Generate files in an empty workspace\n\n```bash\ngo run ./cmd/goflow --workspace D:/scratch-project\n```\n\nThen ask:\n\n```text\nPlease generate an initial README and docs/overview.md for this empty project.\n```\n\n### Explore a linked kit\n\n```text\n/kits binary-analysis-kit\n/workflow-templates binary-triage\n```\n\nFor a copyable materialized version with its own Agent, Skill, MCP helper,\nWorkflow, Team Template, and Policy Rule, see\n[examples/binary-analysis-kit](./examples/binary-analysis-kit).\n\n### Triage binary artifacts\n\n```text\n/workflow skill-chain analyze sample.bin for suspicious imports, strings, and likely attack surfaces\n```\n\nUse a plain workspace path for raw binaries. `@file` references are reserved for\nUTF-8 text content.\n\n## Documentation\n\n- [Installation And Deployment](./docs/install.md)\n- [Architecture](./docs/architecture.md)\n- [Configuration](./docs/configuration.md)\n- [Resources And Settings Guide](./docs/resources.md)\n- [Deployment](./docs/deployment.md)\n- [Release Packaging](./docs/release.md)\n- [MCP Integration](./docs/mcp.md)\n- [MCP Isolation Strategy](./docs/mcp-isolation.md)\n- [MCP Tool Authoring](./docs/mcp-authoring.md)\n- [Scaffold Commands](./docs/scaffolds.md)\n- [Skills](./docs/skills.md)\n- [Skill Authoring](./docs/skill-authoring.md)\n- [Workflow Graphs](./docs/workflows.md)\n- [Updates](./docs/updates.md)\n\n## Status\n\nThe framework is working end-to-end, including:\n- external workspace execution\n- Windows, Linux, and Docker deployment paths\n- built-in Go and Python MCP servers\n- registry-backed workflow execution and approval-aware session state\n- CLI status and session inspection\n- HTTP JSON and SSE runtime transport\n- safer Windows bootstrap without embedded credentials\n\n"}