Your Coding Agent Can Read the Code—but Can It See the App Fail?

TailFlow, an open-source runtime-verification layer for coding agents, captures local application output and exposes it via an MCP server, enabling agents to observe runtime failures without sending logs to a hosted platform. The tool, developed by ThinkGrid Labs, provides commands for initialization, a daemon, an MCP bridge, and a shell client, allowing agents to query logs, group errors, and verify fixes in a continuous loop.

TailFlow gives coding agents compact, queryable evidence from the applications they are changing—without sending local logs to a hosted platform. Coding agents are increasingly capable of navigating repositories, editing multiple files, running tests, and explaining unfamiliar systems. But there is still a gap in the typical agent workflow: The agent can read the code, but it often cannot see what happens after the application starts. A build may pass while the development server fails during startup. A frontend may compile but crash during hot reload. A background worker may begin retrying indefinitely. A Docker container may restart with a configuration error. If the agent cannot observe that output, the workflow usually becomes: agent edits code → checks pass → application fails at runtime → developer notices the terminal error → developer copies the error back to the agent → agent tries again That manual handoff is the problem TailFlow https://github.com/thinkgrid-labs/tailflow is designed to solve. TailFlow is an open-source, local runtime-verification layer for coding agents. It collects output from: TailFlow then exposes the same bounded runtime view through: The goal is not simply to display logs. The goal is to let an agent answer concrete questions: The resulting loop looks like this: capture the stack → establish a baseline → make the change → wait for the runtime outcome → inspect failures → verify the fix Tests remain essential, but they prove only what they exercise. A passing test suite does not necessarily prove that: Runtime output contains evidence that static analysis and isolated tests cannot provide. TailFlow makes that evidence accessible to the agent without requiring the developer to continually watch several terminal tabs. Install TailFlow through npm: npm install -g tailflow This installs four commands: | Command | Purpose | |---|---| tailflow | Interactive TUI and project initializer | tailflow-daemon | Runtime collector and local API | tailflow-mcp | MCP bridge for coding agents | tailflow-logs | Shell client for queries and automation | From the root of a project, run: tailflow init TailFlow detects common runtime sources, including: dev , serve , and start scripts in package.json It then proposes a configuration: TailFlow v0.3.2 TailFlow found: 1. process web: pnpm run dev recommended 2. Docker containers compose.yml recommended 3. file worker: logs/worker.log recommended Select sources: After selection, TailFlow writes a tailflow.toml file. Existing configurations are never replaced unless --force is explicitly provided. For noninteractive environments: tailflow init --yes You can also specify sources directly: tailflow init \ --docker \ --process 'api=go run ./cmd/api' \ --file logs/worker.log Start the collector: tailflow-daemon The local dashboard becomes available at http://127.0.0.1:7878 http://127.0.0.1:7878 . Verify the connection from another terminal: tailflow-logs status tailflow-logs sources For Claude Code: claude mcp add tailflow -- tailflow-mcp For another MCP-compatible client: { "mcpServers": { "tailflow": { "command": "tailflow-mcp" } } } The MCP server gives the agent four focused tools. list log sources Shows which sources are running, exited, failed, or merely observed. This distinction matters. An empty error list does not prove that a service is healthy—it may never have started. get recent errors Returns distinct recent failures with occurrence counts and related stack context. Instead of filling the agent's context window with the same crash 400 times, TailFlow can condense it into one failure group: x400 connection refused: postgres:5432 at Pool.connect ... search logs Returns exact records with source, severity, time, regular-expression, and cursor filters. This is useful when exact values or event ordering matter more than deduplication. wait for logs Waits inside the daemon until a runtime event appears. An agent can wait for: compiled successfully server listening migration complete request finished error|failed|panic This replaces arbitrary sleep-and-poll loops with event-driven verification. One of TailFlow's most important features is its cursor model. Every captured record receives a monotonically increasing sequence number. The agent can save the current cursor before making a change and request only records that appeared afterward. baseline cursor: 241 │ ├── edit application code ├── hot reload begins └── wait after cursor 241 ├── compilation succeeded └── server ready This changes the question from: Are there errors in the logs? to: What happened after this specific edit? TailFlow also reports when the requested cursor has fallen outside its bounded buffer. That prevents an agent from presenting incomplete evidence as proof that nothing failed. TailFlow deliberately gives humans and agents access to the same underlying data. Developers can use the terminal UI: tailflow Or inspect Docker directly: tailflow --docker Shell-based agents and scripts can query the daemon: tailflow-logs errors --since 5m tailflow-logs search 'timeout' --source api tailflow-logs wait --grep 'compiled successfully|Failed to compile' The web dashboard provides live following, severity filters, source counts, and regular-expression search. This shared model makes agent behavior easier to audit: the developer can inspect the same runtime evidence the agent used to reach its conclusion. TailFlow is not trying to replace production observability platforms. It does not provide: Instead, it focuses on one job: Give a coding agent timely, compact evidence from the local software it is changing. The daemon binds to loopback, stores a bounded in-memory buffer, and does not require an account or hosted service. That makes it useful during development, but it also creates important limitations: These boundaries are documented rather than hidden behind a generic “healthy” result. Version 0.3.2 focuses on reducing setup friction and making the project easier to understand and operate. The release includes: tailflow init The broader direction is to make runtime verification a normal step in an agent coding loop—not a manual debugging step performed only after the agent declares success. Planned directions include: TailFlow will remain local-first, bounded for agent context, and explicit about incomplete evidence. TailFlow is open source and licensed under MIT. npm install -g tailflow cd your-project tailflow init tailflow-daemon Then connect your coding agent or explore the local dashboard at http://127.0.0.1:7878 http://127.0.0.1:7878 . Project links: If your coding agent has ever produced a change that looked correct while the application was visibly failing in another terminal, TailFlow is built for that missing part of the loop.