ascii-chat
CLAUDE.md203 starsChanged 8 days agoMITView on GitHub
Current repository guidance (updated 2026-11-08) This guide retains the detailed subsystem notes below, but the repository has changed substantially since the original version was written. The current source of truth for a workflow is the checked-in CMake preset, workflow, topic page, or skill named in the relevant section. If this guide conflicts with those files, inspect the current implementation and update this guide as part of the same change. The recent development cycle has broadened ascii-chat from a TCP/WebSocket- centric…
- Reads credentials
- Installs packages
- Commits and pushes
In this repository11 other files it gives its agents.
- web/AGENTS.mdAGENTS.md
- ascii-chat-c-developmentSkill
- ascii-chat-cli-releaseSkill
- ascii-chat-cross-platform-development-and-or-testingSkill
- ascii-chat-documentationSkill
- ascii-chat-mcp-devSkill
- ascii-chat-python-developmentSkill
- ascii-chat-testingSkill
- ascii-chat-wasm-developmentSkill
- ascii-chat-web-deploySkill
- sentry-commit-messagesSkill
The file
Show its rules and text
We split this CLAUDE.md into the rules it gives an agent
38 rules. About 0 are common, 21 are distinctive, and 17 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈21
Distinctive · estimate
This author's own choices. Worth a look.
17
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 68
Before changing anything, run git status --short --branch.
- Very specific: line 85
When the task is a release, use the CLI release skill.
- Very specific: line 173
Read docs/topics/network.dox, docs/topics/quic.dox, docs/topics/handshake.dox, docs/topics/client_protocol.dox before changing connection …
- Distinctive: line 190
When adding or changing a packet:
- Distinctive: line 192
update packet type registration, length validation, serialization, parsing, logging names, and all transport adapters.
- Distinctive: line 199
update protocol topics and tests before changing the compatibility marker.
- Very specific: line 201
Do not silently fall back from an explicitly requested quic:// endpoint to a different transport.
- Very specific: line 265
Use git log --since='6 months ago' -- <path> and inspect the relevant diffs, including follow-up fixes and tests.
- Very specific: line 303
Use cmake --preset default - use Ninja and don't switch to Makefiles or Visual Studio generators
- Very specific: line 332
Every value-taking option also maps to ASCII_CHAT_<UPPERCASE_NAME> with hyphens changed to underscores.
- Distinctive: line 464
All modes support these (debug builds only):
- Distinctive: line 618
Always use abstraction layer functions, never direct POSIX/Windows APIs.
- Very specific: line 682
Direct detection: Check if URL has a direct file extension (.mp4, .mkv, .m3u8, etc.) or protocol (rtsp://, rtmp://) → use FFmpeg directly …
- Distinctive: line 683
yt-dlp extraction: If not a direct stream, try to extract stream URL using yt-dlp (for YouTube, TikTok, etc.)
- Distinctive: line 684
Fallback: If yt-dlp fails, try FFmpeg as a last resort (may fail for truly unsupported sites)
- Very specific: line 963
When running Criterion test binaries, run individual tests inside of a test suite by using a filter like --filter "*my_test_name_filter*" …
- Very specific: line 970
Always use SAFE_MALLOC/CALLOC/FREE macros
- Very specific: line 979
Always use the logging system (log_debug(), log_info(), etc.) instead of raw fprintf() or printf() calls:
- Distinctive: line 992
Don't write to log file (can't debug post-mortem)
- Very specific: line 998
Use log_*_every() in high-frequency code (video/audio loops)
- Very specific: line 999
Use --grep to filter noise during debugging
- Distinctive: line 1007
All comments in code are important by nature.
- Distinctive: line 1037
All comments in production code should be equally important and carefully considered
- Distinctive: line 1039
If something is truly critical, explain why and what happens if violated
- Very specific: line 1051
Always use asciichat_error_t return types
- Very specific: line 1052
Use SET_ERRNO() for errors with context
- Very specific: line 1053
Use SET_ERRNO_SYS() for system call errors
- Distinctive: line 1054
Check return values and propagate errors up
- Distinctive: line 1135
"Unknown mode or invalid argument": Check command line - mode must come after binary-level options
- Distinctive: line 1151
Connection refused: Check server is running and firewall allows port 27224
- Distinctive: line 1158
Handshake timeout: Check crypto keys match
- Distinctive: line 1166
Leaks at exit: Check memory report. Red numbers indicate leaks.
- Distinctive: line 1172
Use AddressSanitizer in debug builds to find issues:
- Distinctive: line 1187
After stack is exhausted, program waits for manual input
- Very specific: line 1202
Use include/ascii-chat/common/limits.h (also included by common.h) for application limits.
- Very specific: line 1228
Use hostname_to_ascii() from util/url.h for DNS hostname normalization.
- Distinctive: line 1237
Keep each capacity at its narrowest useful scope:
- Distinctive: line 1250
Document bytes versus elements/samples and whether text includes NUL.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
ascii-chat Development Guide for Claude
Current repository guidance (updated 2026-11-08)
This guide retains the detailed subsystem notes below, but the repository has changed substantially since the original version was written. The current source of truth for a workflow is the checked-in CMake preset, workflow, topic page, or skill named in the relevant section. If this guide conflicts with those files, inspect the current implementation and update this guide as part of the same change.
Current State and Recent Direction
The recent development cycle has broadened ascii-chat from a TCP/WebSocket- centric terminal application into a shared native/browser transport stack. The major changes visible in the last six months are:
- The ACIP transport layer now supports native QUIC and browser WebTransport in addition to TCP, WebSocket, and WebRTC paths. Native QUIC and HTTP/3 WebTransport share the server's UDP endpoint and the same ACIP session machinery; do not implement a second protocol path for browser behavior.
- QUIC transport security is layered. TLS 1.3 authenticates the transport endpoint, while ACIP authentication protects the application session and media metadata. Stream traffic and negotiated DATAGRAM traffic have separate readiness, routing, and failure handling. Transport readiness alone is not enough to send media.
- Negotiated QUIC DATAGRAM support carries audio and visual media when the peer permits it. Datagram loss is expected: use the bounded reassembly and video recovery paths rather than assuming ordered delivery. Reliable ACIP streams remain the fallback for peers without usable datagrams.
- Discovery can advertise native QUIC and browser WebTransport endpoints, preserve the authoritative discovery host during handoff, and rotate authenticated application-key epochs while media is live. Discovery and direct transport code must use the shared authenticated-record and rekey abstractions.
- The wire compatibility marker is currently protocol
2.3.0. Change the protocol constants deliberately and update the compatibility tests and release annotation when changing packet layouts, negotiation, or encoded media contracts. - The MCP server is a first-class mode and can render media, serve temporary hosted downloads, and expose browser/native-compatible output formats. Keep MCP cancellation, bind validation, credential-bearing URL redaction, and output cleanup on the existing ownership paths.
- Native rendering now includes selectable renderers, temporal stabilization, motion-aware per-cell history, improved glyph and braille coverage, and browser/native parity work. Rendering hot paths must remain allocation-free, deterministic under tests, and independent of logging or blocking I/O.
- Python test support has migrated to
uvand pytest. Native Python drivers, extractor tests, WebRTC smoke coverage, and many integration tests now use the project test environment rather than a manually managed virtualenv. - SQL discovery queries are embedded from the pinned Sequel/mmmbed toolchain. Generated catalogs must remain consistent across platforms, and the native mmmbed binaries are selected for the host, including Windows ARM64.
- Documentation has a standalone CMake/Doxygen project, curated topic
categories, and a Pages deployment workflow. Documentation is welcome and
encouraged, but do not create random Markdown files under
docs/: files that are not part of the rendered Doxygen navigation are easy to miss and never appear in the browser. Put durable architecture, subsystem, workflow, and task documentation indocs/topics/*.dox, and update the curated Topic Categories page atdocs/topics/index.doxwhen a topic belongs in its navigation. Modify existing rendered documentation freely when it improves the site; keep every new page connected to the Doxygen topic structure.
Repository Rules That Are Easy to Miss
Preserve the working tree
Before changing anything, run git status --short --branch. Existing edits
belong to the user unless they are clearly part of the requested task. Stage
named files only; never use git add . or git add -A while unrelated work is
present. Do not remove build/, dependency caches, generated browser output,
or another task's worktree just to obtain a clean build.
Use the repository's skills and current authorities
The repository's .agents/skills/ guidance is part of the development
contract. For native C work, read ascii-chat-c-development/SKILL.md; for
tests, read ascii-chat-testing/SKILL.md; for Python tooling, read
ascii-chat-python-development/SKILL.md; and for cross-platform builds, read
ascii-chat-cross-platform-development-and-testing/SKILL.md. For public API,
transport, subsystem, option, or workflow changes, read
ascii-chat-documentation/SKILL.md and update the relevant docs in the same
change.
When the task is a release, use the CLI release skill. CLI tags (vX.Y.Z) and
library tags (lib/vX.Y.Z) are independent. Release tags are annotated and
immutable: never move, delete, force-push, or reuse a tag after publishing it.
Prefer abstractions over new parallel paths
Network features belong in the shared transport, ACIP, negotiation, packet, crypto, and media pipelines. Native QUIC, WebTransport, WebRTC, WebSocket, and TCP adapters must satisfy the same transport contract. Do not add a browser-only packet format, a second media queue, or a mode-specific crypto handshake when the shared layer already owns that concern.
Public structures and packet fields have three documentation surfaces: the header/Doxygen comments, the curated topic pages, and the data-structure reference. Keep names, ownership, byte widths, optionality, and lifecycle claims consistent across all three. The generated data-structure summaries describe ownership; they are not permission to expose private implementation details as public API.
Current Build and Test Workflow
The native build uses Clang, Ninja, and the checked-in CMake presets. On
Windows use the native PowerShell environment and the default preset; do not
substitute MSVC or GCC. Reconfigure an existing build rather than deleting it.
# Standard sanitized debug build
cmake --preset default -B build
cmake --build build
# Faster debug build without sanitizer instrumentation
cmake --preset debug-fast
cmake --build build-fast-debug
# Configure, build, and run the complete native test preset
cmake --preset tests
cmake --build --preset tests
ctest --preset all
# Narrow test groups
ctest --preset unit
ctest --preset integration
ctest --preset performanceThe preset names and binary directories in CMakePresets.json are authoritative.
The default preset intentionally has BUILD_TESTS=OFF; use tests or
github when tests are required. release, release-musl, static,
shared, windows-release, docker, coverage, panic, and the web/iOS
configurations have different dependency and instrumentation contracts; do
not infer one preset's behavior from another.
Python commands must use the locked uv environment:
uv sync --project tests/ascii_chat_tests --frozen
uv run --project tests/ascii_chat_tests --frozen pytest tests/python/...
uv run --project tests/ascii_chat_tests --frozen python tests/standalone/...Set Python3_EXECUTABLE to the interpreter returned by the test environment
when configuring CMake if CMake or CTest will invoke Python. Do not use
python -m pip, a system Python, or a hand-created virtualenv. Change Python
dependencies in the appropriate pyproject.toml and lockfile.
For migrated tests, prefer pytest selection and fixtures over invoking old
standalone drivers directly. Use the current test layout under
tests/python/, tests/standalone/, and tests/scripts/; inspect the test's
README or pyproject.toml when a command is unclear. Python lint/type checks
use the locked tooling and are part of the CI contract.
Documentation and formatting checks
The documentation project can be verified without configuring the native application:
cmake -S docs -B build_docs -DASCII_CHAT_SOURCE_DIR="$PWD"
cmake --build build_docs --target docsThe formatter workflow has a dependency-free standalone configuration. Changed C/C++ files are checked with clang-format in CI, and pushes to master may produce a metadata-only formatting commit. Avoid editing generated HTML or browser artifacts by hand; regenerate them through the documented build.
Transport and Protocol Notes
Read docs/topics/network.dox, docs/topics/quic.dox, docs/topics/handshake.dox,
docs/topics/client_protocol.dox before
changing connection setup. Read docs/acip-preparation.md before changing
wire formats. The protocol version constants live in
include/ascii-chat/common/protocol_constants.h.
The connection lifecycle is intentionally staged:
- The adapter establishes transport connectivity and reports transport state.
- QUIC/WebTransport waits for TLS, endpoint trust, and application security readiness; these are distinct from a socket being connected.
- ACIP negotiation exchanges protocol/version and capability information.
- Reliable control and media streams are routed through the shared packet scheduler; optional datagrams are enabled only after capability negotiation.
- Discovery, handoff, and key rotation update shared authenticated records, then media resumes through the normal readiness gates.
When adding or changing a packet:
- update packet type registration, length validation, serialization, parsing, logging names, and all transport adapters;
- preserve packed wire widths independently of application storage widths;
- validate received counts and lengths before indexing, allocating, or serializing;
- cover native, browser/WASM, and fallback transports where the packet is supported;
- update protocol topics and tests before changing the compatibility marker.
Do not silently fall back from an explicitly requested quic:// endpoint to a
different transport. Endpoint URL selection is part of the current browser and
native transport contract. WebTransport uses an advertised HTTPS origin and
HTTP/3, while native QUIC uses the explicit QUIC listener. Both still carry
ACIP traffic and must preserve authentication and cancellation semantics.
Current Media, Audio, and Rendering Notes
Audio capture, preview, mixing, encoding, transport delivery, and playback are separate ownership domains. The audio callback must not perform telemetry, blocking I/O, allocation, or logging. Device changes keep capture alive where possible and use the existing fallback/error-scope behavior. Audio batches may use negotiated datagrams but must retain a reliable path for peers without that capability.
Video frames carry acquisition and telemetry metadata through the shared frame pipeline. Render selection, palette, glyph support, stabilization history, and browser/native output are negotiated or configured through existing options; do not hard-code a renderer in a transport or mode. Temporal stabilization and motion-aware cell history are stateful: reset them on media, dimension, or source changes and test both fresh-frame and transition behavior.
For media URLs, preserve the direct FFmpeg path, yt-dlp extraction path, credential redaction, cancellation, and audio-first stream handling. Use fake yt-dlp fixtures for tests that should not contact a real service. Keep cached stream metadata scoped by URL and extraction options, and do not log secrets embedded in URLs or headers.
Current Tooling and Deployment Notes
The MCP server has native and hosted workflows. Validate bind addresses and download handles, keep temporary artifacts bounded and cancellable, and make HTTP status/error handling use the shared parser. MCP rendering should reuse the same media and renderer pipeline as the native application. Hosted download routes are temporary and must not be treated as permanent public storage.
The query and panic tools are development tools, not production dependencies. The query tool uses the host's LLDB/LLVM facilities and the panic tool builds instrumented source-print variants. Their build files must remain isolated from the normal application target and must not silently add required runtime dependencies to the main binary.
SQL generation is pinned and reproducible. Use the repository's embedded mmmbed/Sequel toolchain and host-specific binaries; do not regenerate catalogs with an arbitrary Go installation. Keep generated SQL stable under formatting, use named bindings, and update all platform catalogs together.
Six-Month History Review Checklist
The recent history added many follow-up fixes to large feature branches. When
reviewing or extending one of those systems, inspect the whole feature family,
not only the first feat: commit. In particular, search history for:
QUIC,WebTransport,ACIP,rekey,datagram,discovery, andhandshakebefore modifying network behavior;pytest,uv,extractor,WebRTC, andsanitizerbefore changing tests;renderer,stabilization,glyph,braille, andterminalbefore changing display behavior;MCP,download,bind,telemetry, andcancellationbefore changing the MCP server;mmmbed,Sequel,SQL catalog, andWindows ARM64before changing discovery query generation;Doxygen,Pages,formatter, andstandalonebefore changing CI or docs.
Use git log --since='6 months ago' -- <path> and inspect the relevant diffs,
including follow-up fixes and tests. Commit messages are useful orientation,
not proof of behavior; verify the current source and tests before documenting
an assertion.
Repository Information
- Repository Owner: zfogg (GitHub username)
- Repository: ascii-chat
- Description: Terminal-based video chat with ASCII art rendering, end-to-end encryption, and multi-client support
Quick Start
C cleanup with defer
In project .c files, include <ascii-chat/tooling/defer/defer.h> and use
defer(action); for block-scoped cleanup. CMake transforms these files before
compilation; use the C development skill and docs/topics/defer.dox for scope,
ownership, restrictions, diagnostics, and build requirements. Do not use defer
in header function bodies or assume it runs on longjmp or process termination.
Building
# Configure with Ninja (default preset)
cmake --preset default -B build
# Build
cmake --build build
# Run tests
cmake --build build --target tests
ctest --test-dir build --output-on-failure --parallel 0IMPORTANT:
- This project uses Clang only, not MSVC or GCC
- Use
cmake --preset default- use Ninja and don't switch to Makefiles or Visual Studio generators - Avoid deleting build/ - just re-run
cmake --preset defaultand rebuild
Running
# Server mode (listens on port 27224)
./build/bin/ascii-chat server
# Client mode (connects to localhost:27224)
./build/bin/ascii-chat client
# Mirror mode (local webcam preview, no networking)
./build/bin/ascii-chat mirror
# Discovery service (ACDS)
./build/bin/acds --port 27225Get full options with: ./build/bin/ascii-chat <mode> --help
Help System & Debug Options
Complete current flag inventory
The lists below were refreshed from the current generated --help output on
2026-11-08. They are intentionally broader than the abbreviated descriptions
later in this file. Always confirm mode availability and defaults with
ascii-chat [mode] --help; binary-level options can be placed before the mode.
Every value-taking option also maps to ASCII_CHAT_<UPPERCASE_NAME> with
hyphens changed to underscores.
Common and logging flags:
-h,--help,-v,--version,--splash-screen--keepawake,--no-keepawake,--check-update,--no-check-update-L,--log-file FILE,--log-level LEVEL,-V,--verbose [VALUE],-q,--quiet,--grep PATTERN--color-scheme NAME,--json,--log-template TEMPLATE,--log-format-console--otel-log-level LEVEL,--otel-endpoint URL,--otel-ca-file FILE,--otel-enabled-telemetry LIST,--otel-realtime-sample-rate VALUE,--otel-realtime-max-per-second INTEGER,--otel-metrics-interval MS,--otel-timeout MS,--otel-queue-capacity INTEGER
Terminal, configuration, and display flags:
-x,--width INTEGER,-y,--height INTEGER,--color-mode VALUE,--show-capabilities,--utf8 BOOLEAN,--strip-ansi,--color BOOLEAN--config FILE,--config-create [FILE],--completions SHELL [FILE],--man-page-create [FILE]--zalgo [LEVEL],--waveform,--fft,--color-filter VALUE,-M,--render-mode VALUE,-P,--palette VALUE,-C,--palette-chars STRING,--renderer luminance|glyph,--stabilize,--stretch,--fps INTEGER,--fps-counter,-S,--snapshot,-D,--snapshot-delay SECONDS,--matrix,--face-follow,--face-follow-debug,--flip-x,--flip-y
Webcam and audio flags:
-c,--webcam-index INTEGER,--test-pattern [0|1],--list-webcams--test-audio,--audio-spectral-agc,--audio-pitch-correct,--spectral-audio,--audio-spectral-gate,--audio-multiband,--audio-adaptive-eq,--audio-fft-size INTEGER,-A,--audio,--microphone-channels INTEGER,--microphone-channel INTEGER,--microphone-index INTEGER,--speakers-index INTEGER,--microphone-volume VALUE,--ivolume VALUE,--speakers-volume VALUE,--volume VALUE,--audio-source VALUE,--audio-capture-source VALUE,--audio-analysis,--no-audio-playback,--encode-audio,--no-encode-audio,--list-microphones,--list-speakers
Media and output flags:
-f,--file FILE,-u,--url URL,-l,--loop,--pause,-s,--seek TIMESTAMP,--yt-dlp-options STRING--render-kitty,--render-file PATH,--render-theme THEME,--render-font FONT,--render-font-size SIZE
Network and discovery flags:
-p,--port PORT,--reconnect-attempts INTEGER,--port-forwarding,--scan,--compression-level INTEGER,--no-compress--discovery-service HOST,--discovery-service-port PORT,--discovery-service-url URL,--discovery-expose-ip,--discovery,--webrtc-bind-address ADDRESS,--webrtc,--no-webrtc,--prefer-webrtc,--webrtc-relay-only,--webrtc-skip-stun,--webrtc-disable-turn,--webrtc-skip-host,--webrtc-ice-timeout MS,--webrtc-reconnect-attempts INTEGER,--stun-servers LIST,--turn-servers LIST,--turn-username NAME,--turn-credential VALUE,--turn-secret VALUE- Server-only listener flags include
--websocket-port PORT,--websocket-tls-cert FILE,--websocket-tls-key FILE,--websocket-tls-key-password VALUE,--max-clients INTEGER,--status-screen,--stats-interval SECONDS, and--no-audio-mixer. - MCP server flags include
--server,--transport http|stdio,--http-origin ORIGIN,--address ADDRESS,--address6 ADDRESS,--http-tls-cert FILE,--http-tls-key FILE,--http-tls-key-password VALUE, and--max-clients INTEGER.
Security and diagnostics flags:
-E,--encrypt,-K,--key KEY,--password PASSWORD,--no-encrypt,--no-auth,--server-key KEY,--client-keys LIST,--discovery-insecure,--discovery-service-key KEY--sync-state TIME,--errno-stacks TIME,--backtrace TIME,--memory-report TIME
Several flags are aliases or paired booleans. In particular, --ivolume is
an alias for --microphone-volume, --volume aliases
--speakers-volume, and --no-* forms explicitly disable defaults that are
otherwise enabled. Options that accept an optional value, such as
--config-create, --man-page-create, --test-pattern, and --zalgo, must
be parsed according to the generated help rather than assumed to require a
following token.
Mode Legend: S=server, C=client, M=mirror, DS=discovery-service, D=discovery
Mode Help Commands
./build/bin/ascii-chat --help(all) - Shows all global flags, modes, examples, environment variables, and keybindings../build/bin/ascii-chat <mode> --help(S, C, M, DS) - Mode-specific help with available options for that mode. Key help key?in interactive mode shows help overlay.
Connection & Addressing Options
--address(S, C, DS) - Bind address for server (supports IPv4/IPv6, syntax 0-2); client connects to this address with[host][:port]format (defaults localhost:27224).--port(S, C, DS) - Port number (default: 27224 for server/client, 27225 for discovery-service).--discovery-service(S, C, D) - Enable discovery service integration for P2P session discovery.--discovery-service-port(S, C, D) - Discovery service server port (default 27225).--max-clients(S) - Maximum concurrent clients (server mode only).
Media Input Options
--file FILE(S, C, M) - Use local file instead of webcam (supports .mp4, .mkv, .webm, etc.; use-f '-'for stdin piping).--url URL(S, C, M) - Stream from HTTP/HTTPS URL, HLS (.m3u8), RTSP, or YouTube/TikTok (via yt-dlp).--yt-dlp-options OPTIONS(S, C, M) - Custom yt-dlp flags for streaming site extraction.
Cryptography & Authentication
--password(S, C) - Password-based authentication (ephemeral DH without identity verification).--key FILE(S, C) - SSH key (ed25519 .pem format) for public key authentication; server advertises its key to clients.--server-key FILE|github:USERNAME|URL(C) - Validate server's public key from local file, fetch from GitHub (github:USERNAME), or HTTP(S) URL (TOFU with known_hosts).--client-keys FILE|github:USERNAME|URL(S) - Validate client public keys from local file, GitHub (github:USERNAME), or HTTP(S) URL (server mode).
Display & Rendering Options
--width(M, C, S) - Override terminal width detection.--height(M, C, S) - Override terminal height detection.--color-mode {auto|none|16|256|truecolor}(all) - Force color output mode; CLAUDECODE auto-detects unless piped to file.--strip-ansi(all) - Remove ANSI escape codes (useful for piping to non-terminal or text files).--show-capabilities(all) - Detect and display terminal capabilities (color level, UTF-8 support), then exit immediately.--splash-screen(C, M, D) - Enable or disable splash screen with ASCII art. Use--splash-screen=falseto disable (overrides CLAUDECODE environment variable).--status-screen(S, DS) - Enable or disable live status screen display. Use--status-screen=falseto disable (overrides non-interactive terminal checks).
Snapshot & Recording
--snapshot(C, M) - Capture exactly one frame and exit (useful for scripting). Gotcha: Doesn't auto-detect terminal dimensions when piped.--snapshot-delay(C, M) - Delay before snapshot (default 0). Script tip: Use--snapshot --snapshot-delay 0 | pbcopyto copy frame to clipboard on macOS.
Logging & Debugging Options
All modes support these (debug builds only):
--log-level {DEV|DEBUG|INFO|WARN|ERROR|FATAL}(all) - Verbosity control; pair with--grepfor filtering specific logs.--log-file PATH(all) - Write logs to file instead of stdout/stderr (useful for post-mortem debugging with--grepfiltering).--grep /PATTERN/FLAGS(all) - Filter logs by regex pattern; flags:i(case-insensitive),F(literal string),C#(context lines),g(highlight matches),I(invert/exclude).--sync-state [TIME](all) - Print sync primitives state (mutex/rwlock/condition variables) at optional time interval.--backtrace [TIME](all) - Print call stack with optional time offset.--memory-report [TIME](all) - Periodic memory usage report; red numbers indicate leaks.
Environment Variables
All --flag-name options map to ASCII_CHAT_FLAG_NAME (hyphens → underscores); precedence: config file < env vars < CLI flags.
CLAUDECODE=1- Auto-set by Claude Code; enables splash screen, auto-detects color/UTF-8, disables status screen (override with--splash-screenor--status-screen).ASCII_CHAT_QUESTION_PROMPT_RESPONSE='y;n;password123'- Stack-based auto-answers for interactive prompts (semicolon-separated; useful for automation/testing).
Binary Modes
ascii-chat binary has four primary modes:
- server - Video broadcast server, handles multiple clients, mixes audio, generates ASCII grid
- client - Connects to server, sends webcam frames, receives mixed ASCII output
- mirror - Local mode for testing webcam/files/ulrs/encoding/format without networking or crypto
- discovery-service - Session signalling and discovery webrtc server
- discovery - The mode that connects via session string via a discovery-service instance. ascii-chat binary runs as this mode by default when you don't pass a mode as a first positional argument.
Debugging Flags
Snapshot Mode (Single Frame Capture)
# Capture exactly one frame and exit
./build/bin/ascii-chat client --snapshot --snapshot-delay 0
# Same thing
./build/bin/ascii-chat client --snapshot -S -D 0
# Capture for N seconds then exit (useful for testing), printing every frame to stdout
./build/bin/ascii-chat mirror --snapshot --snapshot-delay 5
# Common pattern: quick test without continuous capture
./build/bin/ascii-chat mirror --snapshot --snapshot-delay 0 --volume 0Log Filtering with --grep
Searches logs and log headers. Supports two formats:
- Format 1:
/pattern/flags- Regex with flags (case-insensitive, context lines, etc.) - Format 2:
pattern- Plain regex without slashes or flags
# Plain regex format (no slashes, no flags)
./build/bin/ascii-chat server --grep "DEBUG"
./build/bin/ascii-chat server --grep "handshake|crypto"
./build/bin/ascii-chat client --grep "ERROR|WARN"
# Slash format with flags
./build/bin/ascii-chat server --grep "/handshake/i" # Case-insensitive
./build/bin/ascii-chat client --grep "/ERROR/C2" # 2 lines of context
./build/bin/ascii-chat client --grep "/(YO)/F" # Fixed string (literal)
# Flags: i(case-insensitive), F(fixed string), C/A/B(context), g(global highlight), I(invert)
./build/bin/ascii-chat client --grep "/test/igC2"
./build/bin/ascii-chat client --grep "/test/igB1A3"
# Pass --grep multiple times to OR-logic multiple patterns (can mix formats)
./build/bin/ascii-chat client --grep "/test1/igB1A3" --grep "test2"
# Combine with log levels
./build/bin/ascii-chat --log-level debug server --grep "crypto"Other Debug Options
# Log to file instead of stdout+stderr
./build/bin/ascii-chat --log-file /tmp/server.log server
# Increase verbosity
./build/bin/ascii-chat -VV server # -V, -VV, -VVV
# Set log level explicitly
./build/bin/ascii-chat --log-level dev serverError Handling with asciichat_errno_t
ALWAYS use asciichat_error_t for return types, not int:
// ✅ CORRECT
asciichat_error_t process_data(void) {
if (some_error) {
return SET_ERRNO(ERROR_INVALID_STATE, "Failed to process: %s", reason);
}
return ASCIICHAT_OK;
}
// ❌ WRONG
int process_data(void) {
if (some_error) {
log_error("Failed");
return -1; // No context, no error tracking!
}
return 0;
}Error checking:
asciichat_error_t result = do_something();
if (result != ASCIICHAT_OK) {
asciichat_error_context_t ctx;
if (HAS_ERRNO(&ctx)) {
log_error("Operation failed: %s", ctx.context_message);
}
return result;
}Memory Management
Use memory tracking macros, not raw malloc/free:
// ✅ CORRECT
uint8_t *buffer = SAFE_MALLOC(1024, uint8_t *);
client_t *client = SAFE_CALLOC(1, sizeof(client_t), client_t *);
SAFE_FREE(buffer);
// ❌ WRONG
uint8_t *buffer = malloc(1024); // No leak tracking!
free(buffer);Memory reports show at program exit in debug builds. Red numbers indicate leaks.
Platform Abstraction Layer (lib/platform)
Cross-platform support via abstraction:
- lib/platform/posix/ - Linux/macOS implementations
- lib/platform/windows/ - Windows implementations
- lib/platform/abstraction.h - Platform-independent API
Key abstractions:
- Threads:
asciichat_thread_t,acthread_create() - Mutexes:
mutex_t,mutex_init/lock/unlock() - Sockets:
socket_t,socket_close(),INVALID_SOCKET_VALUE - Safe wrappers:
SAFE_GETENV(),SAFE_STRERROR(),platform_open()
Always use abstraction layer functions, never direct POSIX/Windows APIs.
Session Management (lib/session)
The session layer handles:
- display.c - Terminal capability detection, ASCII rendering setup
- splash.c - Intro splash screen with rainbow animation and log capture
- help_screen.c - Interactive help UI
- server_status.c - Server status screen with live log feed
- discovery_status.c - Discovery UI
- session_log_buffer.c - Shared log buffer for session screens
Session Screens (Status + Splash)
Both status screen and splash screen use the same "fixed header + scrolling logs" pattern:
- Fixed header at top (status info or animated ASCII art)
- Logs captured in
session_log_buffer(100-entry circular buffer) - Logs displayed below header, calculated to fill exactly
term_rows - header_lines - 1 - Screen never scrolls past bottom (prevents terminal flashing)
Implementation:
session_log_buffer_init()- Initialize log capture (called by splash/status init)session_log_buffer_append()- Called fromlib/log/logging.cto capture messagessession_log_buffer_get_recent()- Retrieve N most recent entries for displaysession_log_buffer_clear()- Clear initialization logs before screen starts
Testing:
# Manual test script
./tests/manual/test_session_screens.sh
# Server status screen
./build/bin/ascii-chat server --status-screen
# Client splash screen (shows during connection)
./build/bin/ascii-chat clientMedia Resolution and Streaming
ascii-chat supports media from files and URLs using a smart resolution system:
Supported Media Sources
Direct Streams & Files (FFmpeg-handled):
- Local files:
.mp4,.mkv,.webm,.avi,.mov,.flv,.gif,.jpg,.png, etc. - Streaming protocols:
http://,https://,rtsp://,rtmp://, HLS (.m3u8), DASH - Any format or protocol supported by FFmpeg
Complex Streaming Sites (yt-dlp-resolved):
- 1000+ supported sites including YouTube, TikTok, Twitch, Reddit, Instagram, Twitter, etc.
- Requires
yt-dlpinstalled:pip install yt-dlporbrew install yt-dlp - yt-dlp extracts the actual playable stream URL, which is then handled by FFmpeg
Smart Resolution Strategy
The media source resolver (lib/media/source.c) uses this strategy:
- Direct detection: Check if URL has a direct file extension (
.mp4,.mkv,.m3u8, etc.) or protocol (rtsp://,rtmp://) → use FFmpeg directly (fastest) - yt-dlp extraction: If not a direct stream, try to extract stream URL using yt-dlp (for YouTube, TikTok, etc.)
- Fallback: If yt-dlp fails, try FFmpeg as a last resort (may fail for truly unsupported sites)
- Error reporting: Log failures at each step with the
--grepsystem
Usage Examples
# Direct file (FFmpeg handles it)
./build/bin/ascii-chat mirror --file /path/to/video.mp4
# Direct HTTP stream (FFmpeg handles it)
./build/bin/ascii-chat mirror --url "https://example.com/stream.m3u8"
# YouTube video (yt-dlp extracts stream, FFmpeg plays it)
./build/bin/ascii-chat mirror --url "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
# TikTok video (yt-dlp extracts stream)
./build/bin/ascii-chat mirror --url "https://www.tiktok.com/@user/video/123456"
# Custom yt-dlp options
./build/bin/ascii-chat mirror --url "https://www.youtube.com/..." --yt-dlp-options "--no-warnings --restrict-filenames"
# Server streaming media to clients
./build/bin/ascii-chat server --file video.mp4
./build/bin/ascii-chat server --url "https://www.youtube.com/watch?v=dQw4w9WgXcQ"Caching
Stream URLs extracted by yt-dlp are cached for 30 seconds to avoid repeated subprocess calls during initialization (FPS detection, audio probing, format detection). Cache keys include both URL and yt-dlp options.
Debugging Media Resolution
# Watch media resolution process
./build/bin/ascii-chat --log-level debug mirror --file video.mp4 --grep "Media source|resolve|stream"
# Watch yt-dlp execution
./build/bin/ascii-chat --log-level debug mirror --url "https://www.youtube.com/watch?v=..." --grep "yt-dlp"
# Check FFmpeg fallback
./build/bin/ascii-chat --log-level debug mirror --url "https://example.com/unknown-format" --grep "ffmpeg|stream"Implementation Details
- lib/media/yt_dlp.c/h - yt-dlp subprocess integration with caching
- lib/media/source.c - Smart routing logic and media source creation
- include/ascii-chat/options/options.h -
yt_dlp_optionsSTRING option
Cryptographic Protocol
End-to-End Encryption
ascii-chat uses libsodium for E2E encryption by default:
- X25519 - Key exchange
- XSalsa20-Poly1305 - AEAD cipher
- Ed25519 - SSH key signatures
Authentication Modes
# 1. Ephemeral DH (default) - encrypted but no identity verification
./build/bin/ascii-chat server
./build/bin/ascii-chat client
# 2. Password authentication
./build/bin/ascii-chat server --password "secret"
./build/bin/ascii-chat client --password "secret"
# 3. SSH key authentication (TOFU with known_hosts)
./build/bin/ascii-chat server --key ~/.ssh/id_ed25519
./build/bin/ascii-chat client --server-key ~/.ssh/server_id_ed25519.pub
# 4. Fetch keys from GitHub
./build/bin/ascii-chat client --server-key github:zfoggDebugging Crypto Handshake
# Watch handshake process
./build/bin/ascii-chat --log-level debug server --grep "handshake"
./build/bin/ascii-chat --log-level debug client --grep "handshake|crypto"
# Check known_hosts verification
./build/bin/ascii-chat --log-level debug client --grep "known_hosts"See docs/crypto.md for full protocol specification.
ACDS (ascii-chat Discovery Service)
The Discovery Service enables automatic session discovery and connection:
Running ACDS
# Start discovery server
./build/bin/ascii-chat discovery-service --port 27225 --database ./acds.db
# Register with ACDS (server mode)
./build/bin/ascii-chat server --discovery-service --discovery-service-port 27225
# Find sessions via ACDS (client mode)
./build/bin/ascii-chat client --discovery-service --discovery-service-port 27225ACDS Features
- Session registration with unique string identifiers (e.g., "blue-mountain-tiger")
- IP privacy (requires explicit
--discovery-expose-ipconfirmation) - SQLite database for session persistence
- Automatic cleanup of stale sessions
Debugging ACDS
# Server side
./build/bin/ascii-chat --log-level dev server --acds --grep "/acds|discovery/ig"
# Client side
./build/bin/ascii-chat --log-level debug client --acds --grep "/acds|discovery/ig"
# ACDS server itself
./build/bin/acds --log-level debug --grep "/session|register/ig"Network Protocol Debugging
Packet Structure
Every packet has:
- Magic: ASCIICCHAT spelled in hexadecimal as best we could (validation)
- Type: packet_type_t enum
- Length: payload size
- CRC32: payload checksum
- Client ID: sender identification
Common Packet Issues
magic constant in data: Stream desynchronization, missing synchronization
# Debug packet flow
./build/bin/ascii-chat --log-level debug server --grep "/packet|recv|send/ig"CRC mismatches: Data corruption or incomplete reads
# Watch for CRC errors
./build/bin/ascii-chat server --grep "/CRC|checksum/ig"Unknown packet type: Client/server version mismatch
# Check packet types being sent/received
./build/bin/ascii-chat --log-level debug client --grep "/packet_type/ig"Project Structure
ascii-chat/
├── src/ # Mode entry points and binary initialization
│ ├── main.c # Unified binary that routes to mode implementations based on CLI arguments
│ ├── server/ # Server mode implementation for multi-client video streaming and audio mixing
│ ├── client/ # Client mode implementation that connects to server and streams webcam/media
│ ├── mirror/ # Mirror mode for local-only testing of media encoding without networking
│ ├── discovery-service/ # ACDS (ascii-chat Discovery Service) implementation for P2P session discovery
│ ├── discovery/ # Discovery mode client that connects via session strings from ACDS
│ ├── common/ # Shared code and utilities used by multiple modes
│ ├── session/ # Session initialization and lifecycle management across modes
│ ├── tooling/ # Development and debugging tools integrated into the binary
│ └── web/ # Web components and WebRTC integration for browser-based clients
├── lib/ # Core reusable libraries for all modes
│ ├── platform/ # Cross-platform abstractions (threads, mutexes, sockets, file I/O)
│ │ ├── linux/ # Linux-specific implementations using POSIX APIs and system calls
│ │ ├── macos/ # macOS-specific implementations using Cocoa and Darwin APIs
│ │ ├── windows/ # Windows-specific implementations using Win32 APIs
│ │ ├── posix/ # POSIX-compliant implementations for Unix-like systems
│ │ └── wasm/ # WebAssembly implementations for browser environments
│ ├── session/ # Session management UI including splash screens, status displays, and help overlays
│ ├── crypto/ # Encryption, authentication, SSH key parsing, and cryptographic handshakes
│ │ ├── ssh/ # SSH key parsing, format detection, and serialization utilities
│ │ ├── gpg/ # GPG keyring integration and key management operations
│ │ └── handshake/ # Cryptographic handshake protocol implementation and state machine
│ ├── network/ # Network protocol implementation, packet structure, connection handling, and streaming
│ │ ├── tcp/ # TCP connection management and socket handling
│ │ ├── websocket/ # WebSocket protocol implementation for browser connections
│ │ ├── webrtc/ # WebRTC data channels and media stream handling
│ │ ├── acip/ # Custom ACIP protocol for ASCII chat packet transmission
│ │ ├── mdns/ # mDNS service discovery and local network browsing
│ │ ├── nat/ # NAT traversal and port mapping utilities
│ │ ├── rate_limit/ # Connection rate limiting and traffic shaping
│ │ └── consensus/ # Consensus algorithms for distributed state synchronization
│ ├── video/ # Webcam capture, V4L2/AVFoundation drivers, ASCII art rendering, and SIMD optimizations
│ │ ├── webcam/ # Webcam capture drivers (V4L2 on Linux, AVFoundation on macOS)
│ │ ├── h265/ # H.265/HEVC video codec support via FFmpeg
│ │ ├── simd/ # SIMD-optimized video processing (AVX2, NEON, etc.)
│ │ ├── scalar/ # Scalar (non-SIMD) video processing fallback implementations
│ │ └── render/ # ASCII art rendering and terminal output generation
│ ├── audio/ # PortAudio integration for microphone capture, speaker output, and audio mixing
│ ├── media/ # Media file/URL handling with FFmpeg, yt-dlp integration, and format detection
│ ├── discovery/ # ACDS client library for session registration, lookup, and cleanup
│ ├── log/ # Centralized logging system with filtering, formatting, and file output
│ ├── options/ # CLI argument parsing with environment variable mapping and validation
│ │ ├── builder/ # Option descriptor building and validation framework
│ │ ├── parsing/ # CLI argument parsing and environment variable resolution
│ │ ├── registry/ # Global option registry and lookup system
│ │ ├── config/ # Configuration file loading and merging
│ │ ├── completions/ # Shell completion generation (bash, zsh, fish)
│ │ └── manpage/ # Man page documentation generation from option descriptors
│ ├── util/ # Utility functions for strings, IP validation, URLs, and common helpers
│ ├── debug/ # Memory allocation tracking, sync primitive inspection, and performance profiling
│ ├── common/ # Shared structures and utilities used across multiple library modules
│ ├── core/ # Core data structures and abstractions used throughout the codebase
│ ├── ui/ # Terminal UI components for interactive displays and user feedback
│ ├── tooling/ # Internal tools for code generation, validation, and build-time utilities
│ │ ├── defer/ # Deferred execution and resource cleanup helpers
│ │ ├── panic/ # Panic/crash handling and diagnostic reporting
│ │ └── query/ # Query and introspection tools for runtime analysis
│ ├── tests/ # Shared test utilities and fixtures for the test suite
│ ├── uthash/ # Hash table implementation library (vendored dependency)
│ ├── cmake/ # CMake support libraries and configuration helpers
│ └── pkgconfig/ # pkg-config definition files for library installation
├── cmake/ # Build system configuration and utilities
│ ├── dependencies/ # CMake modules for finding/configuring external libraries (PCRE2, FFmpeg, etc.)
│ ├── targets/ # Build target definitions and custom commands for code generation
│ ├── tools/ # CMake utility scripts for template substitution and binary embedding
│ ├── platform/ # Platform-specific CMake configuration (Windows, macOS, Linux)
│ ├── compiler/ # Compiler detection and flag configuration for Clang
│ ├── toolchains/ # CMake toolchain files for cross-compilation and build environments
│ ├── init/ # CMake initialization and project setup helpers
│ ├── install/ # Installation configuration and packaging rules
│ ├── test/ # Test framework configuration and test runner setup
│ ├── utils/ # General-purpose CMake utility macros and functions
│ └── scripts/ # CMake-invoked scripts for build-time operations
├── include/ # Public header files organized by module
│ └── ascii-chat/ # Main header directory with subdirectories mirroring lib/ structure
├── tests/ # Criterion test suite with unit and integration tests for all modules
│ └── unit/ # Unit tests for individual modules organized by component
├── docs/ # Protocol documentation, architecture guides, and usage examples
├── deploy/ # Deployment configurations for ACDS, coturn, and cloud infrastructure
├── web/ # Web applications and browser-based client interfaces
├── images/ # Project images, screenshots, and visual assets
├── git-hooks/ # Git hooks for pre-commit checks and automation
├── witness/ # Test witness files and reference data for regression testing
├── polecats/ # Project management and tracking utilities
├── vcpkg-overlay/ # Custom vcpkg port definitions for dependency management
└── build/ # CMake-generated build output (binaries, object files, generated code)Testing
# Run all tests
cmake --build build --target tests
ctest --test-dir build --output-on-failure --parallel 0
# Run specific test category
ctest --test-dir build --label-regex "^unit$" --output-on-failure
# Run single test
ctest --test-dir build -R "crypto_handshake" --output-on-failureNote: On Intel macOS (not ARM), use Docker for Criterion tests:
docker-compose -f ./tests/docker-compose.yml run --rm ascii-chat-tests bash -c 'build_docker/bin/test_unit_crypto_handshake'On Linux run the tests directly. On Windows Criterion isn't supported.
When running Criterion test binaries, run individual tests inside of a test suite by using a filter like --filter
"*my_test_name_filter*" (don't forget the asterisks).
Development Best Practices
Memory Management Rules
- Always use
SAFE_MALLOC/CALLOC/FREEmacros - Set pointers to NULL after freeing
- Framebuffers own their data - don't double-free
- Buffer pool allocations are automatically tracked
Logging Best Practices
Important: Never use fprintf() or printf() for debug output
Always use the logging system (log_debug(), log_info(), etc.) instead of raw fprintf() or printf() calls:
// ❌ WRONG - bypasses logging system, causes UI artifacts
fprintf(stderr, "[DEBUG] Processing packet\n");
// ✅ CORRECT - goes through logging system
log_debug("Processing packet");Why: Raw fprintf/printf calls:
- Bypass
--grepfiltering (can't isolate specific logs) - Don't write to log file (can't debug post-mortem)
- Interrupt UI rendering (splash screen flashing, scrolling artifacts)
- Ignore
--quietand log level settings
Additional best practices:
- Use
log_*_every()in high-frequency code (video/audio loops) - Use
--grepto filter noise during debugging - Set appropriate log levels: dev < debug < info < warn < error < fatal
- Log to file with
--log-filewhen output would interfere with UI
Comment Style
Never use emphatic comment prefixes like "CRITICAL:", "WARNING:", "IMPORTANT:", etc.
All comments in code are important by nature. Write them in a professional, matter-of-fact tone.
Acceptable prefixes:
- ✅
TODO:- for planned future work - ✅
FIXME:- for known issues that need fixing - ❌
CRITICAL:- everything in production code is critical - ❌
WARNING:- if it's dangerous, explain why, don't just warn - ❌
IMPORTANT:- all comments should be important - ❌
HACK:- if it's a hack, refactor it or explain the constraints
// ❌ WRONG - emphatic style that doesn't add value
// CRITICAL: This must be called before the mutex is destroyed!
// WARNING: Do not modify this without updating the corresponding code!
// IMPORTANT: Buffer must be freed after use!
// ✅ CORRECT - professional, clear, direct
// This must be called before the mutex is destroyed.
// Do not modify this without updating the corresponding code.
// Buffer must be freed after use.
// ✅ CORRECT - actionable markers for future work
// TODO: Add support for IPv6 addresses
// FIXME: Race condition when multiple threads access this simultaneouslyWhy:
- Emphatic prefixes like CRITICAL/WARNING/IMPORTANT make code look unprofessional
- All comments in production code should be equally important and carefully considered
- The comment content itself should convey importance through clear explanation
- If something is truly critical, explain why and what happens if violated
// ❌ WRONG
// CRITICAL: Writer must NOT modify read_index!
// ✅ CORRECT
// Writer must not modify read_index (race condition with reader).Error Handling Best Practices
- Always use
asciichat_error_treturn types - Use
SET_ERRNO()for errors with context - Use
SET_ERRNO_SYS()for system call errors - Check return values and propagate errors up
CMake Best Practices
Required dependencies must be resolved at configure time and linked wherever their
symbols are used. Do not wrap required linking in if(FOO_FOUND) guards that
silently omit a library. Use find_package(... REQUIRED) or the dependency
module's explicit failure checks.
The dependency configuration lives in cmake/deps/Dependencies.cmake and its
included modules. vcpkg.json records managed packages and version overrides;
source-built dependencies also have configuration in cmake/deps/. Consult these
files for platform-specific requirements and pinned versions.
The native build uses:
- Networking and security: libuv, libsodium, OpenSSL, BearSSL, libdatachannel, libwebsockets, miniupnpc, and mdns.
- Audio: PortAudio, Opus, FFTW3, and WebRTC Audio Processing (AEC3), with Abseil support.
- Media and compression: FFmpeg (
avcodec,avformat,avutil,swscale, andswresample), x264/x265 encoder support, and zstd. - Data and configuration: PCRE2, SQLite3, yyjson, tomlc17, and uthash.
- Terminal rendering: libvterm, FreeType2, and Fontconfig where supported.
Requirements vary by platform and build target:
- ALSA is a Linux audio dependency; JACK is an optional PortAudio backend.
- miniupnpc supports automatic port mapping with a graceful fallback when unavailable; follow its dependency module's platform-specific checks.
- mimalloc is controlled by
USE_MIMALLOCand is skipped on iOS. - libexecinfo supplies backtrace support for musl builds.
- Criterion is a test dependency on supported Unix platforms, not Windows.
- Platform libraries, source-build support libraries, and codec dependencies are selected by the corresponding CMake modules. Native, WASM, iOS, static, and shared builds do not all link the same libraries.
Conditionals are appropriate for actual platform, feature, target, and build variants. Optional discovery must correspond to a supported fallback or disabled code path; it must not hide a missing dependency used by compiled code.
find_package(PCRE2 REQUIRED)
target_link_libraries(my-target ${PCRE2_LIBRARIES})Git Workflow
# Never use git add . or git add -A
git add file1.c file2.c file3.h
# Commit with Co-Authored-By for Claude changes
git commit -m "fix: description
# Don't leave an "claude by anthropic" reference in the commit messageWeb Production Deployment
The ascii-chat-www Vercel project serves ascii-chat.com. Its production
branch is deploy-web-www, which starts from the repository default branch
(master). Do not deploy production from ordinary master pushes.
To publish the latest already-pushed master without checking out branches or
disturbing a dirty working tree:
git fetch origin
git push origin origin/master:deploy-web-wwwThis advances deploy-web-www to the current remote master commit and triggers
one Vercel production deployment. Keep updates to deploy-web-www intentional and
infrequent. Vercel can still create preview deployments for non-production
pushes that change web/www or its dependencies; do not rely on Vercel's
Ignored Build Step to avoid deployment quota usage.
Common Issues
Build Issues
"Unknown mode or invalid argument": Check command line - mode must come after binary-level options
# ✅ CORRECT
./build/bin/ascii-chat --log-level info server --port 8080
# ❌ WRONG
./build/bin/ascii-chat server --log-level info --port 8080SIGTTOU when piping: Fixed - program now checks terminal control before modifying terminal
Compilation database for defer tool: Build system automatically handles this
Network Issues
Connection refused: Check server is running and firewall allows port 27224
# Test connectivity
nc -zv localhost 27224Handshake timeout: Check crypto keys match
./build/bin/ascii-chat --log-level debug client --grep "handshake"Memory Issues
Leaks at exit: Check memory report. Red numbers indicate leaks. Common causes:
- Missing
SAFE_FREE()calls - Circular references
- Thread cleanup issues
Use AddressSanitizer in debug builds to find issues:
cmake -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build
./build/bin/ascii-chat mirror --snapshot --snapshot-delay 0Environment Variables
ASCII_CHAT_QUESTION_PROMPT_RESPONSE- Stack-based auto-answer for prompts (for automation/testing)- Single response:
ASCII_CHAT_QUESTION_PROMPT_RESPONSE='y' - Multiple responses:
ASCII_CHAT_QUESTION_PROMPT_RESPONSE='y;n;password123' - Optional trailing semicolon:
ASCII_CHAT_QUESTION_PROMPT_RESPONSE='y;n;' - Responses are popped from the stack as prompts are encountered
- After stack is exhausted, program waits for manual input
- Invalid formats (
;,;;,;y) are rejected
- Single response:
CLAUDECODE=1- Optimize output for LLM (set automatically by Claude Code)SSH_AUTH_SOCK- SSH agent socket for key authenticationLOG_LEVEL- Override log level (DEBUG/INFO/WARN/ERROR/FATAL)ASCII_CHAT_MEMORY_REPORT_BACKTRACE=1- Show backtraces in memory report
Resources
- Crypto Protocol:
docs/crypto.md - Platform Abstraction:
lib/platform/README.md - Build System:
cmake/directory
Shared limits
Use include/ascii-chat/common/limits.h (also included by common.h) for
application limits. Include it directly when only constants are needed.
MAX_SESSION_KEYSbounds keys in one session creation sequence and CLI identity-key arrays; it does not cap persisted key-rotation history.MAX_SESSION_PARTICIPANTSbounds session membership, election, hosting and related arrays.MAX_CLIENTSderives from it. Validate received counts before indexing, allocating or serializing; wire counts are still uint8_t.MAX_HOSTNAME_LENGTHandMAX_HOSTNAME_LABEL_LENGTHare ASCII DNS byte limits excluding NUL (253 and 63). Apply them to ICU-normalized ASCII names, not the UTF-8 input.HOSTNAME_BUFFER_SIZEis the existing 256-byte endpoint/OS hostname capacity, including NUL, also used for bracketed IP literals. It is not DNS validation.MAX_URL_LENGTHexcludes NUL and bounds the normalized schemeless URL, including its addedhttp://prefix. AllocateURL_BUFFER_SIZEbytes for that representation. Explicit-scheme URLs with allocated components remain unrestricted by this scratch-buffer limit; consumers check their own capacity.- Media URL cache capacities include NUL and only govern cache storage. Packed STUN/TURN fields have separate protocol capacities; do not enlarge them to match general URL or hostname buffers.
Lengths from strlen() are bytes, not UTF-8 character counts. Allocate space
for terminators and formatting prefixes/suffixes explicitly. Keep input checks,
overflow checks before size arithmetic, and snprintf error/truncation checks.
A constant documents a bound; it does not prove that untrusted data obeys it.
Reuse semantic constants rather than replacing unrelated equal numeric values.
Use hostname_to_ascii() from util/url.h for DNS hostname normalization. It uses
ICU UTS #46 with nontransitional processing, bidi and contextual checks; check its
return value and preserve the original input separately for display. url_parse()
returns an ASCII host and preserves the path/query/fragment bytes. IP literals
bypass IDNA. Use the canonical host for DNS, TLS SNI/certificate checks and saved
connection identity; do not Punycode URL paths or session names.
Buffer capacities
Keep each capacity at its narrowest useful scope:
common/limits.howns shared application limits.common/buffer_sizes.hprovides generic scratch budgets and encoding widths.- Module headers own contracts shared by their declarations and callers, such
as
audio/limits.h,crypto/sizes.h, andnetwork/acip/acds_sizes.h. - Implementation-only budgets belong in file-local defines or enums. Use a module/file prefix and describe the representation or storage role.
Move established constant names to the owning header and update callers instead of adding aliases just for the move. Reuse semantic contracts; matching numeric values alone do not establish shared ownership.
Document bytes versus elements/samples and whether text includes NUL. Derive
combined storage from its component widths. Use sizeof(array) or
ARRAY_SIZE(array) for operations on owned arrays, and the owning capacity
for pointer-backed allocations, checks, copies, formatting, and loop bounds.
C fixed array bounds require macros or enum constants rather than local
const size_t variables that would create VLAs.
Packed wire storage is a protocol contract. Preserve its width independently of larger application/OS storage, and distinguish it from validation limits.
Literal dimensions remain appropriate for initialized tuples and test vectors, FourCC tags, single scalar/plane outputs, reserved wire padding, byte-domain lookup tables, and SIMD lanes when the surrounding code makes their purpose clear. Boundary-test sizes and expected wire widths should remain independent of implementation constants. Generated and vendored sources retain their own conventions. Arbitrary scratch, queue, parser, and formatting budgets need names.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

