Runtime verification for coding agents.
Coding agents can inspect source code, run tests, and read git history. But a passing build does not prove that the application started, hot-reloaded, handled a request, or stayed healthy afterward.
TailFlow turns local runtime output into compact, queryable evidence so an agent can verify its change against the software that is actually running.
capture the stack → understand the signal → wait for the outcome → verify the change
It collects dev processes, Docker containers, and log files once, then exposes the same bounded view through MCP, a shell CLI, a TUI, and a web dashboard.
An agent can use that evidence to answer:
- Did the service actually start?
- Did my edit trigger a successful rebuild?
- What new failure appeared after my change?
- Is this one error or the same crash repeated 400 times?
The missing part of most agent workflows is not code access. It is runtime awareness.
Without TailFlow
agent edits → code looks correct → you notice a terminal error → you paste it back
With TailFlow
agent edits → waits for runtime output → reads the failure → fixes and verifies
| Job | Capability | Outcome |
|---|---|---|
| Capture | Follow processes, Docker containers, and files in one timeline | The agent sees the stack, not one terminal tab |
| Orient | Track configured source lifecycle and activity | “No errors” is distinguishable from “never started” |
| Understand | Detect severity, group repetitions, and retain stack context | A crash loop becomes one explainable failure |
| Synchronize | Wait server-side for matching runtime output | Async software needs no arbitrary sleep-and-poll loop |
| Compare | Continue from a baseline cursor and report history gaps | New evidence can be separated from pre-existing failures |
| Inspect | Share the model through MCP, shell, browser, and TUI | Developers and agents can examine the same runtime facts |
See the feature guide for use cases, interface mapping, and the boundary of each capability.
TailFlow is deliberately a local runtime-verification layer. It is not a hosted log platform, an APM product, or a replacement for production monitoring.
npm install -g tailflowThis installs four commands: tailflow, tailflow-daemon, tailflow-mcp, and
tailflow-logs.
cd your-project
tailflow initTailFlow detects development scripts, Compose files, and common log files, lets
you choose the sources, and writes tailflow.toml. Use tailflow init --yes to
accept the recommended sources noninteractively.
Nothing is overwritten unless you pass --force. For manual configuration and
explicit --process, --file, or --docker setup, see the
getting-started guide.
tailflow-daemonThe dashboard is now available at http://127.0.0.1:7878.
Check the connection from another terminal:
tailflow-logs status
tailflow-logs sourcesFor Claude Code:
claude mcp add tailflow -- tailflow-mcpFor another MCP client:
{
"mcpServers": {
"tailflow": {
"command": "tailflow-mcp"
}
}
}The MCP client starts tailflow-mcp; you keep tailflow-daemon running in the
project. The MCP process is stateless and connects to the daemon at
http://127.0.0.1:7878 by default.
For installation alternatives, configuration recipes, and troubleshooting, see the getting-started guide.
The features come together in one workflow:
1. Check that the expected sources are running
2. Record the latest cursor as a baseline
3. Make the code change
4. Wait for the rebuild, request, job, or failure caused by that change
5. Read distinct errors or exact lines if the result needs investigation
6. Repeat until the runtime evidence matches the intended outcome
Four focused MCP tools support that loop:
| Tool | Use it for |
|---|---|
list_log_sources | Confirm which services started, exited, failed, or were observed |
get_recent_errors | Read distinct recent failures with counts and stack-trace context |
search_logs | Inspect exact lines and event ordering with filters and cursors |
wait_for_logs | Wait for a rebuild, error, or other runtime event without polling — require_new keeps a previous run's line from satisfying it |
See TailFlow for agents for arguments, output contracts, workflow patterns, shell commands, and the HTTP API.
The same sources are available without an agent.
tailflow # sources from tailflow.toml
tailflow --docker # add all running containers
npm run dev | tailflow # inspect one piped process| Key | Action |
|---|---|
/ | Filter by substring or regular expression |
j / k, ↓ / ↑ | Scroll; scrolling up pauses follow mode |
G | Return to the latest line and resume following |
p | Toggle JSON pretty-printing |
q, Ctrl-C | Quit |
tailflow-logs errors --since 5m
tailflow-logs search 'timeout' --source api
tailflow-logs wait --grep 'compiled successfully|Failed to compile'
tailflow-logs sourcesAdd --json for machine-readable output. Exit codes distinguish success, bad
requests, wait timeouts, and an unavailable daemon.
tailflow-daemon serves an embedded dashboard at
http://127.0.0.1:7878 with source counts, severity filters, regex search, and
scroll-aware live following.
| Command | Purpose | Runs for |
|---|---|---|
tailflow-daemon | Collect logs, retain the buffer, serve HTTP/SSE and the dashboard | Your development session |
tailflow-mcp | Bridge one MCP client to the daemon over stdio | The MCP client session |
tailflow-logs | Make one query from a shell or script | One command |
tailflow | View configured sources in an interactive terminal | Your TUI session |
The npm package requires no Rust toolchain and downloads only the binary package for the current operating system and CPU.
npm install -g tailflow
# or run without a permanent install
npx tailflow@latest --dockerPrebuilt downloads support macOS ARM64/x64, Linux ARM64/x64, and Windows x64. They are attached to each GitHub release.
Build from source with Rust 1.88 or newer:
git clone https://github.com/thinkgrid-labs/tailflow.git
cd tailflow
cargo install --path crates/tailflow-tui
cargo install --path crates/tailflow-daemon
cargo install --path crates/tailflow-agentThe important boundaries are:
- TailFlow listens on loopback and has no authentication or TLS. It is intended for one developer machine, not a shared or internet-facing server.
- The log buffer is memory-only and bounded. History is lost when the daemon restarts, and very active stacks can evict older records.
- Severity detection and error fingerprinting are heuristics. Unusual log formats may be classified or grouped imperfectly.
- Docker support follows all running containers from the local Docker daemon; there is no first-class Compose-service selection or Kubernetes source yet.
- TailFlow observes text output. It does not collect traces, metrics, profiles, or application state.
Read limitations and operational boundaries before using TailFlow in automation or with sensitive logs.
| Guide | Contents |
|---|---|
| Documentation index | Where to start for each task |
| Getting started | Installation, setup recipes, configuration, and troubleshooting |
| Features | Capabilities organized by the problem and outcome |
| TailFlow for agents | MCP tools, shell client, workflow patterns, and HTTP API |
| Architecture | Components, data flow, invariants, and repository layout |
| Limitations | Security, retention, inference, and source boundaries |
| Roadmap | Planned directions and explicit non-goals |
| Contributing | Development environment and pull requests |
| Changelog | Version-by-version changes |
The next priorities are reducing setup friction, making before/after verification more direct, and improving source selection and correlation. Likely directions include direct MCP transport from the daemon, optional daemon auto-start, Compose-aware discovery, cursor-based error diffing, and request correlation.
The roadmap describes direction, not a release commitment. See the full roadmap.
Contributions are welcome. Please read CONTRIBUTING.md and open an issue before starting a large feature or architectural change.
cargo fmt --all
cargo clippy --all-targets --all-features -- -D warnings
cargo test --allMIT — see LICENSE. © 2026 ThinkGrid Labs.