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