The Problem

Chat interfaces force spatial thinking—handwriting, diagrams, equations—into linear text. PenEcho replaces the chat box with a shared canvas where users write, sketch, and reason spatially, and AI responds in place. This matters for math, engineering, and design work where the visual arrangement of ideas carries meaning.

What This Does

PenEcho is a browser-based canvas application backed by a Node.js server. Users draw on a sparse 20,000 x 20,000 canvas; the browser sends cropped visual atlases plus geometry to the server, which routes requests to one of three executors: OpenAI-compatible APIs, local Codex CLI, or local Claude CLI. Responses appear as editable drafts on the canvas.

The core logic lives in public/app.js (202 functions, the largest file at ~3,900 lines), with geometry helpers in public/draw.js and public/selection.js. Server-side orchestration is in server.js (83 functions), CLI argument handling in cli.js, and provider-specific adapters in claude-cli.js and codex-cli.js.

How It Is Wired

Execution starts in cli.js:488 (main), which parses arguments, loads environment configuration, and starts the server. The browser entry point is public/index.html, loading public/app.js. The most heavily routed functions—setStatusKey, t, and render—are each called from 19 places, making them the highest-blast-radius changes in the codebase.

The system touches three external surfaces: AI model inference (via api-config.js and configure-ui.js), filesystem operations (11 functions in server.js, cli.js, and codex-cli.js), and one outbound network call. The shortest traced path from entry to external effect is main -> apiConfigurationIssues, which checks provider configuration before making API calls.

The module graph shows no circular dependencies, but cli.js (instability 0.83) and server.js (0.75) are unstable hubs—they import many modules and are imported by few, meaning changes to them ripple outward. api-config.js, claude-cli.js, and codex-cli.js are stable leaves with zero imports, serving as configuration and adapter layers.

How To Use It

git clone https://github.com/moses-y/penecho
cd penecho
npm install
npm start

Configuration requires either API keys (OpenAI-compatible or Anthropic) or local CLI tools (codex or claude on PATH). The server reads environment variables for API credentials; CLI mode requires the respective binaries installed. server.js handles provider normalization and validation.

Real-World Use

A student working through a calculus problem: draw the function, lasso it, and ask for a derivative. The canvas sends the cropped region to the server, which routes to the configured executor (e.g., Claude CLI), receives a structured draft, and renders it beside the original marks. The user accepts, rejects, or edits before it becomes part of the canvas.

Code Health & Issues

Static analysis found 11 issues (1 high, 10 medium). The high-severity finding: public/app.js, server.js, and test/server-security.test.js are oversized (up to 3,927 lines), making changes risky and hard to review. Medium findings include high branching density in api-config.js, claude-cli.js, and codex-cli.js (27 branch points over 44 lines in one case), and 11 duplicated 6-line blocks across 6 files.

SDLC observations: CI exists but never runs the 9 test files—a green check without assertions. No dependency update bot, no vulnerability scanning, and persist-credentials is not disabled on checkout. One dependency (@inquirer/prompts) is one major version behind.

The Bottom Line

PenEcho solves a real problem for spatial reasoning workflows and has a sensible architecture: stable provider adapters, a clear server-client split, and good test coverage that CI currently ignores. The main risks are the oversized app.js and the CI gap. Worth adopting for teams doing math or diagram-heavy work with AI, but fix the CI test execution before trusting the green check.