{{project-name}}

A Rust workspace scaffold for TUI + daemon applications. A long-running daemon ({{project-name}}d) owns all state and serves clients over a local Unix socket; thin clients -- a CLI ({{project-name}}) and an ASCII ratatui TUI ({{project-name}}-tui) -- connect to it and share one source of truth. The skeleton compiles, its tests pass, and CI is green; the real work each command performs is yours to fill in.

This project was generated from a cargo-generate template. Create a new one with:

cargo generate --git https://git.blobfish.icu/public/rust-tui-daemon-template --name my-app

Workspace layout

The repository is a Cargo workspace (edition 2024) under crates/:

• {{project-name}}-core -- the shared contract both ends of the socket depend on: the IPC protocol (Request/Response/Event), length-prefixed JSON wire framing, the config schema, byte-unit formatting, and the shared error type.
• {{project-name}}-daemon -- the background service (binary {{project-name}}d, the Unix trailing-d convention). Owns the manager/state, an event bus, and the Unix-socket server.
• {{project-name}}-cli -- the terminal client (binary {{project-name}}). A thin layer that turns subcommands into protocol requests.
• {{project-name}}-tui -- a ratatui frontend (binary {{project-name}}-tui), three-panel and ASCII-only.

Plus xtask/ (automation), scripts/ (the deps.dev health check), deny.toml, systemd/, and .pre-commit-config.yaml. Agent/developer docs live in AGENTS.md and agents/.

Quick start

cargo build --workspace          # build everything
cargo xtask ci                   # fmt, clippy, test, cargo-deny (the CI gate)

Run the daemon, then drive it from another terminal:

target/debug/{{project-name}}d &          # start the daemon
target/debug/{{project-name}} ping        # -> pong
target/debug/{{project-name}} add hello   # -> added #1
target/debug/{{project-name}} list        # -> #1  Pending  hello
target/debug/{{project-name}}-tui         # interactive UI (press q to quit)
target/debug/{{project-name}} shutdown    # stop the daemon

The socket defaults to $XDG_RUNTIME_DIR/{{project-name}}/{{project-name}}d.sock; override it per command with --socket, or via {{project-name | shouty_snake_case}}_SOCKET.

IPC

Each message is a 4-byte big-endian length prefix followed by that many bytes of UTF-8 JSON. A client sends a Request and the daemon replies with a Response; after Subscribe, the daemon streams Events. See agents/protocol.md.

Development

• cargo xtask ci -- the full gate (fmt, clippy -D warnings, test, deny).
• cargo xtask precommit -- the fast subset; pre-commit install wires it in.
• cargo xtask deps-health -- the deps.dev advisory/scorecard report.

Start with AGENTS.md, then the topic docs under agents/.

Installing the daemon as a service

cargo install --path crates/{{project-name}}-daemon   # {{project-name}}d -> ~/.cargo/bin
mkdir -p ~/.config/systemd/user
cp systemd/{{project-name}}.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now {{project-name}}

License

Released under the WTFPL -- do what the fuck you want to.