If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/tokio-rs/console shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 4w ago
• 27+ active contributors
• Distributed ownership (top contributor 31% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live tokio-rs/console repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/tokio-rs/console.

What it runs against: a local clone of tokio-rs/console — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in tokio-rs/console | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 58 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of tokio-rs/console. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/tokio-rs/console.git
#   cd console
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of tokio-rs/console and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "tokio-rs/console(\\.git)?\\b" \\
  && ok "origin remote is tokio-rs/console" \\
  || miss "origin remote is not tokio-rs/console (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 58 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~28d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/tokio-rs/console"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

tokio-console is an interactive debugging and diagnostics tool for async Rust programs running on Tokio. It streams live telemetry from instrumented applications via gRPC/Protocol Buffers and displays real-time task metrics, resource usage, and async operation details in a top-like TUI, enabling developers to inspect what async tasks are doing and identify bottlenecks. Workspace monorepo with four members: tokio-console/ (TUI CLI client), console-subscriber/ (tracing-subscriber Layer for instrumentation), console-api/ (protobuf definitions and tonic gRPC bindings generated from proto/ files), and xtask/ (build/release helpers). Core wire protocol defined in console-api/proto/ (async_ops.proto, common.proto), with TypeScript UI code likely under the main console crate.

Rust developers building high-concurrency async applications with Tokio who need to understand task scheduling, identify blocking operations, and debug performance issues in production-like environments. Contributors are Tokio ecosystem maintainers and async Rust practitioners.

Actively developed and production-ready: the repo has reached versioned releases (visible in CHANGELOG.md entries), maintains a monorepo with 577K lines of Rust, runs comprehensive CI/CD via GitHub Actions (audit, release-plz automation), and the Tokio team actively maintains it. Not a toy project.

Low risk: owned by the Tokio organization (tokio-rs) with established CODEOWNERS and governance, no single-maintainer bottleneck apparent. Mild risk: gRPC/protobuf dependency chain is non-trivial (tonic, prost), and the wire protocol is version-locked (breaking changes between subscriber and console versions could cause compatibility issues). TypeScript UI code (113K lines) suggests frontend complexity that may move slower than backend.

Active maintenance: release-plz.yml and release.yml workflows indicate automated versioning/publishing; audit.yml runs dependency security checks; flakehub-publish-tagged.yml suggests Nix flake packaging support. No breaking changes evident in file list, but version management is automated. Likely in steady-state improvement mode (bug fixes, feature refinement) rather than major overhaul.

git clone https://github.com/tokio-rs/console.git
cd console
cargo build --release
# To run the console against an instrumented app:
cargo run --bin tokio-console -- --target <instrumented-app-address>

Daily commands:

cargo build --release
# Run instrumented app with console-subscriber enabled (in its Cargo.toml):
# RUST_LOG=... cargo run --bin your_app
# In another terminal, connect console:
cargo run --bin tokio-console
# TUI appears with live task list, resource details (semaphore, sleep), and timing metrics.

• console-api/proto/async_ops.proto: Defines the gRPC wire format for streaming task, resource, and operation metrics—the contract between subscriber and client
• console-subscriber/Cargo.toml: Main instrumentation crate; users add this as a dependency and Layer to enable console telemetry collection
• tokio-console/src/: TUI client implementation; contains the interactive views (task list, details panels) that display streamed diagnostics
• .github/workflows/ci.yml: CI pipeline validation; shows how builds, tests, and releases are verified across the workspace
• Cargo.toml: Workspace root defining the four-member monorepo structure and shared profiles (dist profile for release builds)

Adding wire protocol fields: edit console-api/proto/*.proto, regenerate via cargo build (tonic codegen). Fixing TUI display logic: modify files in tokio-console/src/ (likely view, input, state modules). Extending instrumentation: modify console-subscriber/src/ to hook new async events. Testing: check test modules in each crate (convention: #[cfg(test)] mod tests). Run cargo test --workspace to validate all changes.

Proto regeneration: editing .proto files requires running cargo build in console-api/ to regenerate Rust bindings via tonic; forgetting this causes compilation errors. Version compatibility: console (client) and console-subscriber (instrumentation) must be compatible wire-protocol versions, or diagnostics will fail silently or hang. Flake users: .envrc implies Nix development environment; non-Nix users may miss pinned dependency versions. Release process: release-plz automates versioning but requires Git tags and token permissions; manual release PRs can conflict. No explicit database or long-lived services required—console is a client-only tool.

• gRPC bidirectional streaming — console uses streaming gRPC to push live task metrics from subscriber to client in real-time, avoiding polling overhead
• tracing-subscriber Layer — console-subscriber implements this trait to hook into the tracing ecosystem without requiring code changes in user apps—only a dependency addition
• Protocol Buffers schema versioning — console depends on proto file compatibility between subscriber and client; breaking changes require careful migration and version negotiation
• Async task scheduling introspection — Understanding task wake events, state transitions (spawned→running→waiting), and runtime metrics is the core diagnostic capability
• TUI (Text User Interface) design patterns — console implements interactive views with real-time updates similar to top or htop; understanding state management and redraw optimization is key to contributing
• Resource contention detection — console visualizes resource wait times (semaphores, mutexes, sleep) to identify why tasks are blocked—critical for async debugging

• tokio-rs/tokio — The async runtime being debugged; console-subscriber instruments Tokio's task scheduler and reactor directly
• tokio-rs/tracing — The diagnostic logging framework that console-subscriber wraps as a Layer; foundational to telemetry collection
• hyperium/tonic — The gRPC/protobuf Rust implementation used for the wire protocol between subscriber and console
• tokio-rs/bytes — Efficient byte buffer handling for streaming protocol messages over gRPC connections
• flamegraph-rs/flamegraph — Complementary Rust profiling tool; console focuses on async task scheduling while flamegraph shows CPU time—often used together

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for console-api protobuf message serialization/deserialization

The console-api crate contains generated protobuf code (console-api/src/generated/) but there are no visible integration tests validating that messages round-trip correctly or that the proto definitions compile correctly across different scenarios. This is critical since the entire inter-process communication depends on these messages being correctly serialized/deserialized between tokio-console and console-subscriber.

• [ ] Create console-api/tests/ directory with integration tests
• [ ] Add tests that serialize and deserialize each message type defined in console-api/proto/*.proto files
• [ ] Test edge cases like empty repeated fields, missing optional fields, and maximum/minimum values
• [ ] Verify the generated code in console-api/src/generated/ compiles without warnings
• [ ] Add a CI step (or extend existing CI in .github/workflows/ci.yml) to run these integration tests

Complete the truncated README.md with missing documentation sections

The README.md ends abruptly with 'the diagnostic toolkit consists of multiple comp' - indicating incomplete documentation. Given this is a complex debugger tool with multiple workspace members (tokio-console, console-subscriber, console-api, xtask), new users need clear documentation on: architecture overview, quick-start guide, and how the components interact. This is the first impression for contributors and users.

• [ ] Complete the truncated sentence describing the toolkit components
• [ ] Add 'Architecture' section explaining the relationship between tokio-console (CLI), console-subscriber (instrumentation), and console-api (protocol)
• [ ] Add 'Getting Started' section with example code showing how to instrument a tokio app
• [ ] Add 'Project Structure' section mapping each workspace member to its purpose
• [ ] Reference the existing proto files in console-api/proto/ to document the protocol layer
• [ ] Consider adding a diagram showing data flow from instrumented app → console-subscriber → tokio-console client

Add proto file validation and linting to CI pipeline

The repo contains multiple .proto files (console-api/proto/*.proto including async_ops.proto, resources.proto, tasks.proto, trace.proto) but there's no visible protobuf linting in the CI workflow (.github/workflows/ci.yml). Without proto linting, breaking changes can slip through undetected, and proto style inconsistencies can degrade code quality across the protocol layer.

• [ ] Add buf.build configuration file (buf.yaml) to root and/or console-api/ directory
• [ ] Configure buf to lint all .proto files in console-api/proto/ against standard rules
• [ ] Extend .github/workflows/ci.yml to run 'buf lint' step
• [ ] Add breaking change detection step to CI (buf breaking) to catch incompatible proto modifications
• [ ] Document the proto development guidelines in CONTRIBUTING.md with references to buf configuration

• Add missing documentation examples in console-subscriber/README.md showing minimal 3-line setup code (Layer addition + app instrumentation) with accompanying runnable example under examples/
• Implement unit tests for console-api/proto/ field validation logic (e.g., ensure Task IDs are non-zero, timestamps monotonic) that currently may be uncovered
• Add CSS classes for dark-mode theme support to the TUI components (if TypeScript/HTML is used); currently screenshots show light theme only, but no dark-mode assets in assets/

The tokio-console repository demonstrates a generally secure posture with proper security reporting channels and security-focused CI/CD workflows. However, there are minor gaps: the SECURITY.md documentation is incomplete, environment configuration files need proper exclusion from version control, and dependency auditing robustness is unclear. The multi-member workspace structure requires consistent security practices across all components. No evidence of hardcoded secrets, injection vulnerabilities, or misconfigured infrastructure was found based on the provided file structure and content. Recommend completing security documentation and enforcing stricter dependency audit practices.

• Medium · Incomplete SECURITY.md Policy — SECURITY.md. The SECURITY.md file is truncated and incomplete. It cuts off mid-sentence in the 'Vulnerability coordination' section, which may indicate missing or incomplete security disclosure policies. This could create confusion about the complete security reporting process. Fix: Complete the SECURITY.md file with full vulnerability coordination details, including expected response timelines, disclosure process, and any other relevant security policies.
• Low · Potential Exposure of Development Environment Configuration — .envrc. The repository contains .envrc file which is commonly used with direnv for environment management. While the file itself is not visible in the provided content, the presence of this file in version control could potentially lead to environment variable exposure if not properly configured. Fix: Ensure .envrc is in .gitignore to prevent accidental commits of environment configurations. Use a .envrc.example template instead, and document environment setup in CONTRIBUTING.md.
• Low · No Evidence of Dependency Audit Workflow — .github/workflows/audit.yml. While an audit.yml workflow file exists in .github/workflows, there is no visibility into its configuration. Without a proper dependency audit mechanism, vulnerable transitive dependencies could go undetected. Fix: Ensure the audit workflow runs cargo audit regularly (at minimum on each PR and commit). Configure dependabot or similar tools for automated dependency updates and security alerts.
• Low · Multiple Workspace Members - Increased Attack Surface — Cargo.toml (workspace configuration). The workspace contains multiple members (tokio-console, console-subscriber, console-api, xtask) which increases the overall attack surface. Each member needs independent security scrutiny. Fix: Maintain separate security reviews for each workspace member. Consider CODEOWNERS file restrictions per member. Document security responsibilities in CONTRIBUTING.md.
• Low · Protobuf Files in Version Control — console-api/proto/. The repository contains .proto files (async_ops.proto, common.proto, etc.) which are compiled to generated Rust code. While this is normal practice, protobuf parsing vulnerabilities in dependencies should be monitored. Fix: Ensure prost and other protobuf crates are kept up-to-date. Monitor security advisories for protobuf parsing libraries. Consider pinning critical dependency versions.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.