docs: redesign test subcommand as headless mode by Pertempto · Pull Request #46 · mrs-electronics-inc/time-tracker

Pertempto · 2026-01-08T18:21:11Z

I had shelley implement the test subcommand, but it turned out to actually be a bit inconvenient for the agent to access the image files from the temporary directory.

It works much better if we just scrap the temporary directory output and the stdin/stdout system. Instead just serve headless mode through a simple HTTP server.

I also found a better name to describe what this actually is - headless rather than test.

Key changes: - HTTP server on port 8080 instead of stdin/stdout JSON - POST /input returns both render_url and raw ANSI - GET /render/latest.png for easy browser viewing - GET /render/{timestamp}.png for specific renders - Larger default terminal size (120x30) - just recipes for starting test server

'headless' better describes running the TUI without a terminal, which is the standard term (like headless browsers).

github-actions · 2026-01-08T18:23:17Z

specs/007-headless-subcommand.md — The API returns a raw ansi string in the POST response. Please specify whether this is the full ANSI stream or the visible cell grid (ANSI normalized). Recommend returning both: a normalized text grid (no cursor/OSC/VT control sequences) for easy text assertions, and the raw ANSI when needed for debugging.

github-actions · 2026-01-08T18:23:26Z

Changes Requested

Bind the HTTP server to localhost by default and add an explicit --bind/--host flag to expose publicly. Document CORS/auth expectations.
Add a configurable render retention policy (max renders or TTL) or document why unbounded retention is acceptable.
Clarify what the returned ansi value represents; prefer returning both a normalized text grid and the raw ANSI stream.

Summary of Changes

New spec specs/007-headless-subcommand.md introducing a headless subcommand that starts an HTTP server to accept input commands and serve PNG renders and ANSI output.
Removes the prior test subcommand spec (specs/007-test-subcommand.md), replacing it with the headless design and updated API.

Overall Feedback

The move from a filesystem/stdin approach to an HTTP server is reasonable and will be more convenient for agents and debugging, but the current spec omits important operational/security details (binding, CORS, auth). Please address those to avoid accidental exposure.
The design covers useful features (POST /input, render URLs, ANSI) and sensible defaults; once the operational/security options and render retention/response normalization are specified, this will be a solid foundation for headless testing.

Please update the spec with the requested changes and ping me when ready for another review.

Thanks! 🎯

- /render/latest now redirects (302) to timestamped URL - /state includes render_url and ansi in response

Update run-docker to bind port 8080 for headless subcommand instead of adding new recipes.

Examples: - just input key j - just input type "hello world" - just input resize 40 160

- Fix terminal size references to 160x40 - Add task for error responses on invalid actions - Clarify initial render happens on startup - Clarify input recipe wraps curl

- Bind to localhost (127.0.0.1) by default - Add --bind flag to optionally expose to network - Document lack of authentication and CORS - Note that server is for local dev/testing only

- Add --max-renders flag (default: 100) to prevent unbounded memory growth - Implement FIFO eviction when limit reached - Clarify that ansi field contains raw View() output with all escape sequences

Pertempto · 2026-01-08T18:43:03Z

Wow! surprisingly on-point feedback for the code review bot!

specs/007-headless-mode.md

Reduced verbosity while keeping all essential information: - Problem section removed (context is clear) - Usage examples consolidated - Design decisions summarized - Task list unchanged

- Add backticks around all endpoint references - Unify GET /state and POST /input response formats - Update creation date to January 8

- Must use FiraCode Nerd Font for powerline symbol support - Add task for configuring bubbletea ANSI output to non-tty

Address clarifying questions from implementation: - Key format uses tea.KeyMsg.String() (enter, esc, ctrl+c, etc.) - Mode values from CurrentMode.Name (list, start, help, stats) - Timestamp format with all dashes for URL safety - Link to Ghostty source for color palette reference

- Add full 16-color palette table with hex values - Specify pure black (#000000) as default/background color - Remove external Ghostty reference

Pertempto · 2026-01-08T20:06:40Z

I did a quick test with fresh Shelley agent. Here were the clarifying questions that should be better addressed in the spec.

addressed with two newest commits

specs/007-headless-mode.md

exedev-shelley added 2 commits January 8, 2026 18:16

docs: rename test subcommand to headless

89e110e

'headless' better describes running the TUI without a terminal, which is the standard term (like headless browsers).

This comment was marked as resolved.

Sign in to view

exedev-shelley added 8 commits January 8, 2026 18:23

docs: improve /render/latest and /state endpoints

0d77331

- /render/latest now redirects (302) to timestamped URL - /state includes render_url and ansi in response

docs: use run-docker recipe instead of separate headless recipes

b755e1a

Update run-docker to bind port 8080 for headless subcommand instead of adding new recipes.

docs: remove custom port option from run-docker example

fb4f330

docs: use port 8484 as default (TT = 84 84 in ASCII)

45512c3

docs: add input recipe for sending commands to headless server

1b37de3

Examples: - just input key j - just input type "hello world" - just input resize 40 160

docs: clarify AGENTS.md task to include new recipes

378f8bf

docs: rename from 'headless subcommand' to 'headless mode'

1afdb50

docs: use 'action' instead of 'cmd' in JSON protocol

9376d18

Pertempto changed the title ~~docs: redesign test subcommand as headless subcommand~~ docs: redesign test subcommand as headless mode Jan 8, 2026

exedev-shelley added 6 commits January 8, 2026 18:33

docs: replace 'command' with 'action' throughout spec

a28ebc0

docs: increase default terminal size to 240x60

2686a33

docs: use 160x40 terminal size to catch small-terminal layout issues

1893c87

docs: fix inconsistencies and add missing tasks

4c26cb8

- Fix terminal size references to 160x40 - Add task for error responses on invalid actions - Clarify initial render happens on startup - Clarify input recipe wraps curl

docs: add security considerations for headless mode

3a9bf51

- Bind to localhost (127.0.0.1) by default - Add --bind flag to optionally expose to network - Document lack of authentication and CORS - Note that server is for local dev/testing only

docs: add render retention limits and clarify ANSI output format

dff6a0f

- Add --max-renders flag (default: 100) to prevent unbounded memory growth - Implement FIFO eviction when limit reached - Clarify that ansi field contains raw View() output with all escape sequences

docs: add task for documenting security considerations

92a037b

Pertempto marked this pull request as ready for review January 8, 2026 18:44

Pertempto self-assigned this Jan 8, 2026

Pertempto requested a review from bambam955 January 8, 2026 18:44

Pertempto commented Jan 8, 2026

View reviewed changes

specs/007-headless-mode.md Show resolved Hide resolved

exedev-shelley added 3 commits January 8, 2026 18:49

docs: condense spec to focus on key design points

96b64c2

Reduced verbosity while keeping all essential information: - Problem section removed (context is clear) - Usage examples consolidated - Design decisions summarized - Task list unchanged

docs: improve headless spec formatting and consistency

ba6f247

- Add backticks around all endpoint references - Unify GET /state and POST /input response formats - Update creation date to January 8

docs: add width/height/mode to response format

b43a709

docs: clarify font requirement and add bubbletea non-tty task

6457e71

- Must use FiraCode Nerd Font for powerline symbol support - Add task for configuring bubbletea ANSI output to non-tty

This comment was marked as resolved.

Sign in to view

exedev-shelley added 2 commits January 8, 2026 20:04

docs: embed ANSI color palette directly in spec

8c7bee5

- Add full 16-color palette table with hex values - Specify pure black (#000000) as default/background color - Remove external Ghostty reference

docs: specify lipgloss.SetColorProfile for non-tty ANSI output

4b71c9a

Pertempto mentioned this pull request Jan 8, 2026

feat: headless mode #47

Merged

7 tasks

bambam955 reviewed Jan 9, 2026

View reviewed changes

specs/007-headless-mode.md Show resolved Hide resolved

bambam955 approved these changes Jan 9, 2026

View reviewed changes

fix: formatting

b3554e1

Pertempto merged commit bcda246 into main Jan 12, 2026
1 check passed

Pertempto deleted the spec/007-test-subcommand-http-redesign branch January 12, 2026 19:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: redesign test subcommand as headless mode#46

docs: redesign test subcommand as headless mode#46
Pertempto merged 25 commits intomainfrom
spec/007-test-subcommand-http-redesign

Pertempto commented Jan 8, 2026 •

edited

Loading

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

github-actions bot commented Jan 8, 2026

Uh oh!

github-actions bot commented Jan 8, 2026

Uh oh!

Pertempto commented Jan 8, 2026

Uh oh!

Uh oh!

This comment was marked as resolved.

Pertempto commented Jan 8, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Pertempto commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

github-actions bot commented Jan 8, 2026

Uh oh!

github-actions bot commented Jan 8, 2026

Changes Requested

Summary of Changes

Overall Feedback

Uh oh!

Pertempto commented Jan 8, 2026

Uh oh!

Uh oh!

This comment was marked as resolved.

Pertempto commented Jan 8, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Pertempto commented Jan 8, 2026 •

edited

Loading