154 lines
6.2 KiB
Markdown
154 lines
6.2 KiB
Markdown
---
|
|
phase: quick
|
|
plan: 260322-27k
|
|
type: execute
|
|
wave: 1
|
|
depends_on: []
|
|
files_modified: [README.md]
|
|
autonomous: true
|
|
requirements: [quick-readme]
|
|
|
|
must_haves:
|
|
truths:
|
|
- "README.md exists at repo root with project overview, features, installation, usage, and build sections"
|
|
- "Content is Linux-only, no macOS instructions"
|
|
- "Placeholder section for animated TUI screenshot with recording tool suggestions"
|
|
artifacts:
|
|
- path: "README.md"
|
|
provides: "Project README"
|
|
min_lines: 80
|
|
key_links: []
|
|
---
|
|
|
|
<objective>
|
|
Create a comprehensive README.md at the repository root for the tcptop project.
|
|
|
|
Purpose: First point of contact for anyone discovering the project — explains what it is, how to install, how to use, and how to build from source.
|
|
Output: README.md
|
|
</objective>
|
|
|
|
<execution_context>
|
|
@/Users/zrowitsch/local_src/tcptop/.claude/get-shit-done/workflows/execute-plan.md
|
|
@/Users/zrowitsch/local_src/tcptop/.claude/get-shit-done/templates/summary.md
|
|
</execution_context>
|
|
|
|
<context>
|
|
@.planning/quick/260322-27k-add-project-readme/260322-27k-CONTEXT.md
|
|
@tcptop/src/main.rs (CLI struct with all flags)
|
|
@tcptop/src/tui/event.rs (keybindings reference)
|
|
@tcptop/Cargo.toml (version, metadata)
|
|
@rust-toolchain.toml (nightly pin)
|
|
@doc/PACKAGING.md (packaging reference, do not duplicate)
|
|
</context>
|
|
|
|
<tasks>
|
|
|
|
<task type="auto">
|
|
<name>Task 1: Create README.md</name>
|
|
<files>README.md</files>
|
|
<action>
|
|
Create README.md at the repo root with these sections in order:
|
|
|
|
1. **Title and tagline** — `# tcptop` followed by a one-line description: "A real-time, top-like TUI for per-connection network statistics, powered by eBPF." No badges.
|
|
|
|
2. **Screenshot placeholder** — A section with a placeholder for an animated terminal recording. Include a comment or note like:
|
|
```
|
|
<!-- TODO: Add animated terminal recording -->
|
|
> Screenshot coming soon. To create one, consider:
|
|
> - [VHS](https://github.com/charmbracelet/vhs) by Charmbracelet — scriptable terminal recordings to GIF
|
|
> - [asciinema](https://asciinema.org/) — terminal session recorder (renders as asciicast or GIF via agg)
|
|
> - [ttygif](https://github.com/icholy/ttygif) — converts ttyrec recordings to GIF
|
|
```
|
|
|
|
3. **Features** — Bulleted list of key features:
|
|
- Real-time per-connection view (bytes, packets, latency, state)
|
|
- eBPF-based kernel tracing (low overhead, no polling)
|
|
- Sortable table with mnemonic keys and column navigation
|
|
- Live text filtering (`/` to search)
|
|
- Process attribution (PID and process name)
|
|
- TCP and UDP support with protocol filtering
|
|
- CSV logging mode for offline analysis (`--log`)
|
|
- Bootstraps pre-existing connections on startup
|
|
- Graceful privilege handling (clear error when not root)
|
|
|
|
4. **Requirements** — Linux only. List:
|
|
- Linux kernel 5.15+ (BTF support required for eBPF CO-RE)
|
|
- Root privileges (sudo) — required for eBPF program loading
|
|
|
|
5. **Installation** — Two sub-sections:
|
|
- **From .deb/.rpm** — point to Releases page and show `sudo dpkg -i` / `sudo rpm -i` commands. Link to `doc/PACKAGING.md` for building packages from source.
|
|
- **From source** — see "Building from Source" section below.
|
|
|
|
6. **Usage** — Show `sudo tcptop` as the basic invocation. Then a table or list of CLI flags with descriptions (derive from the Cli struct in main.rs):
|
|
- `--port <PORT>` — filter by port (source or destination)
|
|
- `--pid <PID>` — filter by process ID
|
|
- `--process <NAME>` — filter by process name (substring match)
|
|
- `-i, --interface <IFACE>` — network interface to monitor
|
|
- `--tcp` — show only TCP connections
|
|
- `--udp` — show only UDP connections
|
|
- `--interval <SECS>` — refresh interval in seconds (default: 1)
|
|
- `--log <FILE>` — log to CSV file (headless mode, no TUI)
|
|
|
|
Then a **Keyboard shortcuts** sub-section as a table:
|
|
| Key | Action |
|
|
| `q` / `Ctrl-C` | Quit |
|
|
| `j` / `Down` | Scroll down |
|
|
| `k` / `Up` | Scroll up |
|
|
| `/` | Enter filter mode |
|
|
| `Esc` | Clear filter |
|
|
| `Enter` | Confirm filter / Sort by selected column |
|
|
| `Tab` / `Right` | Next column |
|
|
| `Shift-Tab` / `Left` | Previous column |
|
|
| `?` | Toggle help overlay |
|
|
| `c` | Toggle extra columns |
|
|
| `r` / `R` | Sort by rate in / rate out |
|
|
| `p` / `P` | Sort by PID / protocol |
|
|
| `n` | Sort by process name |
|
|
| `s` | Sort by state |
|
|
| `t` | Sort by RTT |
|
|
| `a` / `A` | Sort by local / remote address |
|
|
|
|
Include 2-3 usage examples:
|
|
```
|
|
sudo tcptop --port 443 --tcp
|
|
sudo tcptop --pid 1234 --interval 2
|
|
sudo tcptop --log connections.csv
|
|
```
|
|
|
|
7. **Building from Source** — Prerequisites and build steps:
|
|
- Rust nightly toolchain (pinned via `rust-toolchain.toml` to `nightly-2026-03-20`)
|
|
- `bpf-linker` — `cargo install bpf-linker`
|
|
- LLVM 21+ (for bpf-linker on some systems)
|
|
- Build command: `cargo build --release -p tcptop`
|
|
- Binary location: `target/release/tcptop`
|
|
- Note that `cargo xtask` is NOT used — aya-build handles eBPF compilation via build.rs automatically.
|
|
|
|
8. **License** — MIT (per Cargo.toml)
|
|
|
|
Do NOT include: contributing guidelines, architecture section, macOS instructions, CI badges.
|
|
</action>
|
|
<verify>
|
|
<automated>test -f README.md && wc -l README.md | awk '{if ($1 >= 80) print "OK: " $1 " lines"; else print "FAIL: only " $1 " lines"}'</automated>
|
|
</verify>
|
|
<done>README.md exists at repo root with all specified sections, Linux-only focus, animated screenshot placeholder with tool recommendations, and accurate CLI/keybinding documentation</done>
|
|
</task>
|
|
|
|
</tasks>
|
|
|
|
<verification>
|
|
- README.md exists at repo root
|
|
- Contains all 8 sections specified above
|
|
- No macOS content
|
|
- CLI flags match the actual Cli struct in main.rs
|
|
- Keybindings match the actual event.rs handler
|
|
- Build instructions reference the correct nightly version from rust-toolchain.toml
|
|
</verification>
|
|
|
|
<success_criteria>
|
|
README.md committed with comprehensive project documentation covering overview, features, installation, usage (CLI + keyboard), build from source, and license. Screenshot placeholder with recording tool suggestions included.
|
|
</success_criteria>
|
|
|
|
<output>
|
|
After completion, create `.planning/quick/260322-27k-add-project-readme/260322-27k-SUMMARY.md`
|
|
</output>
|