[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-93447":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":16,"stars30d":16,"stars90d":15,"forks30d":15,"starsTrendScore":16,"compositeScore":17,"rankGlobal":9,"rankLanguage":9,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":19,"hasPages":19,"topics":21,"createdAt":9,"pushedAt":9,"updatedAt":30,"readmeContent":31,"aiSummary":9,"trendingCount":15,"starSnapshotCount":15,"syncStatus":32,"lastSyncTime":33,"discoverSource":34},93447,"penecho","erickong\u002Fpenecho","erickong","Think with AI beyond the chat box. A shared canvas for handwriting, equations, diagrams, and spatial reasoning.",null,"JavaScript",364,46,4,3,0,184,75.02,"GNU Affero General Public License v3.0",false,"main",[22,23,24,25,26,27,28,29],"ai","canvas","claude","codex","education","handwriting","nodejs","visual-thinking","2026-07-22 04:02:09","\u003Ch1 align=\"center\">\n  \u003Cimg src=\"public\u002Fpenecho-readme-header.png\" alt=\"PenEcho\" width=\"760\">\n\u003C\u002Fh1>\n\n\u003Cp align=\"center\">\u003Cstrong>Think with AI beyond the chat box.\u003C\u002Fstrong>\u003C\u002Fp>\n\n\u003Cp align=\"center\">PenEcho is a shared canvas where handwriting, equations, diagrams, and spatial context become part of the conversation.\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fdiscord.gg\u002F3jrPJ3mXdX\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDiscord-Join%20the%20community-5865F2?style=for-the-badge&logo=discord&logoColor=white\" alt=\"Join the PenEcho Discord\">\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Ferickong\u002Fpenecho\u002Fstargazers\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Ferickong\u002Fpenecho?style=for-the-badge&logo=github&logoColor=white&color=f5b301\" alt=\"Star PenEcho on GitHub\">\n  \u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\u003Cem>Built in the open by a small community — \u003Ca href=\"https:\u002F\u002Fdiscord.gg\u002F3jrPJ3mXdX\">come help shape it\u003C\u002Fa>.\u003C\u002Fem>\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Ferickong\u002Fpenecho\u002Freleases\u002Fdownload\u002Fv0.1.0\u002Fpenecho-demo.gif\" alt=\"PenEcho turning handwritten work into an editable visual answer\" width=\"100%\">\n\u003C\u002Fp>\n\n## Think on the canvas\n\nPut a question, equation, diagram, or half-formed idea anywhere on the canvas and pause. PenEcho reads your marks and their spatial relationships, then answers beside them. You can work through a problem without translating every step into a chat message or rebuilding it with rigid diagram tools.\n\n- Get answers, hints, explanations, continuations, formulas, plots, and diagrams directly on the canvas.\n- Move, resize, accept, or discard every AI draft before it becomes part of your work.\n- Draw naturally with a stylus or mouse, then pan and zoom across a sparse `20,000 x 20,000` canvas.\n- Draw a freehand lasso around confirmed ink to move, resize, or recolor it locally; accepting or cancelling a selection never triggers an AI request.\n- Choose Arcane, Sci-fi, or Research mode to match the kind of problem you are exploring.\n- Save lightweight snapshots locally in your browser. Starting a new canvas can overwrite the current snapshot, save a new copy, or continue without saving; unconfirmed AI drafts are never included.\n- Export confirmed canvas ink as a cropped PNG with one `512`-pixel tile of paper margin on every side.\n\nPenEcho keeps a small local runtime and only allocates `512 x 512` tiles where ink exists, so the huge logical canvas does not become a huge bitmap.\n\n## What's new in 0.5.0\n\n- **Per-request reasoning control.** The canvas toolbar now provides six convenient levels for matching response quality and speed to the task: `Configured` keeps the saved model or CLI setting, `None` disables reasoning where the provider supports it, `Low` is the fastest lightweight option, `Medium` is the balanced everyday choice, `High` adds more depth for difficult work, and `Max` requests the provider's highest practical level (`xhigh` for OpenAI and `max` for Anthropic). The choice applies to the next requests without reopening the configuration center.\n- **High-resolution PNG export.** Use `Export` in the toolbar to download the confirmed canvas as a crisp PNG. PenEcho crops to the smallest rectangle containing the ink and adds one paper tile of margin on every side, making the result easy to share or archive without exporting the entire sparse canvas.\n- **Typed canvas text.** Select the `Text` tool, click anywhere on the paper, and enter text in one or more independent movable, resizable editors. Plain text is the default and preserves explicit line breaks. Each editor has an independent `MD+TeX` preview toggle for basic Markdown and inline LaTeX such as `$x^2$`, `A_x^y`, `\\frac{a}{b}`, and `\\sqrt{x}`; unsupported or incomplete markup stays literal. Use the `?` button beside `MD+TeX` for a short reference and examples. The editor keeps its default size and font in screen pixels while you pan or zoom, and becomes confirmed ink only after `Ctrl\u002FCmd + Enter` or the check button; either confirmation or cancellation returns to the pen tool. Automatic AI recognition starts after confirmation, never while you are still typing.\n- **Persistent AI drafts.** AI results remain on the canvas while you continue writing. Accept or discard them explicitly; the check and close actions include a short input guard so an accidental follow-up tap does not immediately start another request.\n\n## How it works\n\n```mermaid\nflowchart LR\n  User[\"Handwriting, equations, and sketches\"] --> Canvas[\"Browser canvas\u003Cbr\u002F>sparse confirmed tiles\"]\n  Canvas --> Atlas[\"Cropped visual atlas\u003Cbr\u002F>plus geometry\"]\n  Atlas --> Server[\"PenEcho server\u003Cbr\u002F>validation and prompt\"]\n  Server --> Executor{\"Configured executor\"}\n  Executor --> API[\"API mode\u003Cbr\u002F>OpenAI-compatible or Anthropic\"]\n  Executor --> Codex[\"Codex CLI mode\u003Cbr\u002F>local codex exec\"]\n  Executor --> Claude[\"Claude CLI mode\u003Cbr\u002F>local claude -p\"]\n  API --> Draft[\"Structured editable draft\"]\n  Codex --> Draft\n  Claude --> Draft\n  Draft --> Canvas\n```\n\nThe browser sends only the relevant canvas crop and geometry. The server validates the request, uses the selected executor, and returns a movable draft that stays separate from confirmed ink until you accept it.\n\n## Quick start\n\nYou need [Node.js 18.17+](https:\u002F\u002Fnodejs.org\u002F) and one of the following: an API key, an authenticated [Codex CLI](https:\u002F\u002Fdevelopers.openai.com\u002Fcodex\u002Fcli), or an authenticated [Claude Code CLI](https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Foverview).\n\n```bash\nnpm install -g penecho\npenecho configure\npenecho\n```\n\n`penecho configure` opens the interactive configuration center. Its main menu contains `LLM source`, `Settings`, and `Exit`. Use the arrow keys and Enter to navigate:\n\n- `LLM source -> Claude CLI` selects a detected, recommended, default, or manually entered model and an effort level. Opus 4.8 or newer is recommended; Sonnet and Opus 4.6 can respond but may produce weaker canvas results.\n- `LLM source -> Codex CLI` selects a model and effort. GPT-5.5 or newer is required for good results, `gpt-5.6-sol` is recommended, and `xhigh` is the highest listed Codex effort.\n- `LLM source -> API` selects the OpenAI-compatible or Anthropic\u002FClaude-compatible request format, then asks for the URL, model, effort, and hidden key. Kimi K3 uses the OpenAI-compatible format with model `k3`; current testing recommends `medium`. Anthropic API offers `none` to disable thinking and defaults new configurations to the recommended `medium` adaptive-thinking level. PenEcho does not set `temperature` for API requests, connection checks, or CLI invocations; each provider and model uses its own default. Existing values are offered as defaults and a blank key keeps the saved key.\n- `Settings` controls the unified model timeout, the image format sent to every model executor, request recording and retention, listening interface and port, and initial Auto AI delay. WebP is the default; PNG is also available. The delay can also be changed on the canvas.\n\nEvery LLM page ends with `Test & Save`, and PenEcho always saves before checking. Codex CLI uses a fast offline check: it verifies the executable and login, then reads `codex debug models --bundled` to confirm the selected model exists. It does not run inference, attach an image, refresh the online catalog, or consume model tokens. Claude CLI and API configuration still send one small real request to verify the selected endpoint\u002Fmodel settings. Whether a check passes or fails, the configuration remains saved and the UI returns to the parent menu with a clear diagnostic.\n\nThe canvas toolbar exposes a fixed-width clickable `Reasoning` menu beside Auto AI for frequent per-request changes: `Configured`, `none`, `low`, `medium`, `high`, and the provider's highest practical level. `Configured` omits the per-request effort field so the server preserves the configured custom effort or the underlying CLI default. The last explicit position maps to `xhigh` for OpenAI API and Codex CLI, and to `max` for Anthropic API and Claude CLI. `none` sends OpenAI `reasoning_effort=none`; for Claude it disables thinking. Model support remains provider-dependent, so an endpoint may reject a level its selected model does not implement. The saved `AI_EFFORT` initializes this control, while a toolbar change overrides it for subsequent canvas requests without rewriting the configuration file. The menu closes after a selection or five seconds of inactivity.\n\nThe default configuration is `~\u002F.penecho\u002Fconfig.env`. API credentials are plaintext in this local file, receive owner-only permissions on POSIX systems, and are never sent to browser code. Protect it like any other credential. If `penecho` is started before this file exists, it opens the configuration center automatically in an interactive terminal.\n\nUse a different env-style configuration file for a particular launch when needed:\n\n```bash\npenecho configure --config .\u002Fteam.env\npenecho --config .\u002Fteam.env\n```\n\nAn explicit `--config` file replaces the default global file for that command. PenEcho does not automatically read a project-directory `.env` or a package-directory `.env`.\n\n### CLI prerequisites\n\nInstalling the Codex desktop app alone does not guarantee that a `codex` executable is available on the shell `PATH`. Install and authenticate the CLI separately before selecting Codex:\n\n```bash\nnpm install -g @openai\u002Fcodex@latest\nhash -r\ncodex --version\ncodex login status\n```\n\nIf needed, run `codex login`. Claude CLI mode similarly requires an installed and authenticated Claude Code CLI, normally through `claude auth login`.\n\nPenEcho uses the selected CLI locally and does not need an API key for that source. Normal startup checks the executable and login without consuming model tokens. Codex `Test & Save` additionally verifies the selected model against the installed CLI's bundled catalog without making a model request; Claude `Test & Save` sends a small real request.\n\nCanvas requests through Codex use `codex exec --json`. PenEcho returns as soon as Codex emits the final agent message and `turn.completed`; if the CLI process remains alive afterward, it is terminated and cleaned up in the background instead of delaying the canvas response.\n\nClaude CLI requests use one isolated `claude -p` turn with tools, agents, MCP, prompt suggestions, session persistence, and other nonessential background traffic disabled. Selecting effort `none` sets `MAX_THINKING_TOKENS=0`, causing Claude Code to send `thinking.type=disabled`; because `none` is not a valid Claude CLI effort value, PenEcho also passes an internal `low` effort and per-process `--settings` override to neutralize any user-level `CLAUDE_CODE_EFFORT_LEVEL=max`. Selecting `low`, `medium`, `high`, or `max` leaves thinking enabled and applies the chosen value through both Claude's `--effort` flag and the same settings override. PenEcho incrementally validates the stream and returns as soon as Claude emits its successful final `result`; any attempted tool use aborts the request, while a CLI process that remains alive after the result is terminated and cleaned up in the background.\n\nTransient launch overrides remain available:\n\n```bash\npenecho doctor --codex\npenecho --codex --model gpt-5.6-sol --effort xhigh\npenecho --claude --model opus --effort max\npenecho --port 4000\n```\n\n`--model`, `--effort`, and `--port` apply only to that process and take precedence over the selected configuration file. Omit them to use the saved choice or the underlying CLI default. Other model-specific effort strings are accepted and passed through.\n\n### Run from this source directory\n\nInstall dependencies, expose this checkout's `penecho` executable through npm, configure it, and start it through the same production entry point:\n\n```bash\nnpm install\nnpm link\npenecho configure\npenecho\n```\n\n`npm link` creates the local command link; it does not publish the package. There is no separate build step and local development does not use `npm start`.\n\nOpen [http:\u002F\u002Flocalhost:3888](http:\u002F\u002Flocalhost:3888). Other devices on the same trusted LAN can use `http:\u002F\u002F\u003Cthis-computer-LAN-IP>:3888`.\n\n## Recommended model configurations\n\nThese recommendations balance answer quality against the latency of PenEcho's real canvas workload. They are based on current hands-on testing rather than synthetic benchmarks; actual response time still varies with the provider, canvas complexity, image size, and reasoning behavior.\n\n| Model | Effort | Quality and speed | Recommended use |\n| --- | --- | --- | --- |\n| `claude-opus-4-8` | `medium` | Strong quality with a better latency balance | Recommended Opus default for everyday canvas work |\n| `claude-opus-4-8` | `high` | Higher reasoning quality, with longer and more variable waits | Complex handwriting, mathematics, diagrams, or layout decisions where quality matters more than speed |\n| Fable 5 (`claude-fable-5` or `fable`) | `medium` | Very good results; in current tests, often around half the response time of `gpt-5.6-sol` at `xhigh` | A fast, high-quality general-purpose choice |\n| Kimi K3 (`k3`) | `medium` | Very good quality in the current comparison; `medium` keeps the quality\u002Fspeed balance practical | Recommended Kimi\u002FAPI default for demanding canvas work |\n| `gpt-5.6-terra` | `low` to `high` | Surprisingly strong and responsive; current PenEcho canvas tests produced better results than `gpt-5.6-sol` with fast response times | Recommended OpenAI option across a flexible range of quality and latency targets |\n| `gpt-5.6-luna` | `xhigh` | Very good canvas results with strong response speed | A responsive quality-first option when `xhigh` reasoning is appropriate |\n| `gpt-5.6-sol` | `high` | Good enough for most requests and more responsive than `xhigh` | Recommended Sol default when responsiveness matters |\n| `gpt-5.6-sol` | `xhigh` | Very good results, but slower and more variable | Quality-first Sol configuration for difficult canvas tasks |\n\nGoogle models have not been tested yet. Contributions are welcome: if you try Gemini or another Google model, please share the model ID, provider or executor, reasoning configuration, approximate latency, and a representative canvas example in an issue.\n\n## Token use and cost\n\nFor a typical PenEcho canvas request, total output usage—including hidden reasoning tokens when the provider reports them—roughly follows the selected effort level:\n\n| Effort | Typical output usage | Practical guidance |\n| --- | --- | --- |\n| `low` | Around `1,000` tokens | Usually enough for most everyday canvas requests |\n| `medium` | Around `3,000` tokens | More reasoning headroom for recognition, mathematics, diagrams, and layout |\n| `xhigh` or `max` | Around `5,000–8,000` tokens | Common for quality-first `gpt-5.6-sol` and other maximum-effort requests; expect higher latency and cost |\n\nThese are practical estimates rather than enforced PenEcho limits. Actual usage can vary substantially by model, provider, canvas complexity, and reasoning behavior. The cost example below continues to use the typical `low` case: `10,000` input tokens and `1,000` output tokens. At standard short-context API rates, that would be:\n\n- `gpt-5.6-sol`: `10,000 x $5.00 \u002F 1M + 1,000 x $30.00 \u002F 1M = $0.080`\n- `gpt-5.6-terra`: `10,000 x $2.50 \u002F 1M + 1,000 x $15.00 \u002F 1M = $0.040`\n- `gpt-5.6-luna`: `10,000 x $1.00 \u002F 1M + 1,000 x $6.00 \u002F 1M = $0.016`\n\nAt those example quantities, that is about 1.6 to 8 cents per request. Medium, `xhigh`, and `max` requests can cost more because their reasoning tokens are billed as output. Prices can change, so check the [OpenAI API pricing](https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fpricing) page for current rates.\n\nIf you sign in to Codex with ChatGPT, PenEcho uses the Codex usage included with your plan instead of an API key. Included limits vary by plan, and additional usage may require ChatGPT credits. See [Codex pricing](https:\u002F\u002Flearn.chatgpt.com\u002Fdocs\u002Fpricing) for current plans and limits. Claude CLI mode similarly uses the account authenticated by Claude Code; it is distinct from Anthropic API billing.\n\n## Help test more models\n\nPenEcho supports model selection independently for API, Codex CLI, and Claude CLI execution. Model behavior still varies. If you find a model-specific issue, please open an issue with the executor, model name, a reproducible canvas example, expected and actual results, and a screenshot with secrets removed.\n\n## Safe deployment\n\nPenEcho listens on `0.0.0.0:3888` by default so localhost and trusted-LAN access work immediately. Choose the deployment boundary that matches your executor:\n\n- **Codex CLI and Claude CLI modes:** use them only on the local machine or a trusted, directly connected LAN. A valid request starts a local CLI process, so do not expose either mode directly to the public internet or an untrusted reverse proxy. Both work immediately from localhost and LAN addresses without a public-origin setting. PenEcho checks the Host, client network, exact Origin, process-lifetime session cookie, and JSON content type before launching the selected CLI. Each valid new request immediately supersedes the prior request; it never waits in a queue or returns a busy response.\n- **API mode:** local, LAN, proxy, and remote requests are intentionally accepted without PenEcho-level Host or Origin restrictions. If you expose it publicly, place it behind HTTPS, authentication, rate limiting, and request-size controls. Keep the selected configuration file and provider keys private; credentials remain in the Node.js process and are never sent to browser code.\n\nFor either mode, keep debug artifacts and request tracing disabled in production unless you are actively diagnosing a problem, and never publish configuration files, logs, screenshots, or saved requests containing private content. When request recording is enabled in `Settings`, each valid AI request is stored under `~\u002F.penecho\u002Flogs\u002Frequests` by default, including the source `atlas.png`, the outbound image, credential-redacted request body, raw and parsed responses, fallback details, and final status. The UI also displays this path and configures retention.\n\n## Useful configuration\n\nThe configuration center writes these settings to `~\u002F.penecho\u002Fconfig.env`, or to the file selected with `--config`:\n\n| Setting | Purpose |\n| --- | --- |\n| `AI_PROVIDER` | Executor: `api`, `codex-cli`, or `claude-cli` |\n| `AI_API_FORMAT` | API request format: `openai` (default example) or `anthropic` |\n| `AI_API_URL` \u002F `AI_API_KEY` | API endpoint and credential; used only in API mode |\n| `AI_API_MODEL` | Model used in API mode |\n| `AI_EFFORT` | Startup reasoning effort for the canvas control; the toolbar's `Configured` option preserves this value verbatim, including custom names, while an empty CLI value leaves the CLI default untouched; Anthropic API and Claude CLI support `none` (wire value `thinking.type=disabled`), while OpenAI sends `reasoning_effort=none`; explicit toolbar levels override this value per request without modifying the file |\n| `AI_TIMEOUT_SECONDS` | Unified timeout for API, Codex CLI, and Claude CLI model attempts; default 180, allowed range 10–600 |\n| `PENECHO_AI_IMAGE_FORMAT` | Image format sent to API, Codex CLI, and Claude CLI: `webp` (default) or `png` |\n| `CODEX_CLI_MODEL` | Optional model override for Codex CLI mode |\n| `CLAUDE_CLI_MODEL` | Optional alias or model-ID override for Claude CLI mode |\n| `AUTO_AI_DELAY_SECONDS` | Initial delay before automatic recognition; the browser control can override it from 0 to 10 seconds |\n| `PENECHO_REQUEST_TRACE` | Save local per-request image, outbound request, response, and outcome traces; disabled by default |\n| `PENECHO_REQUEST_TRACE_LIMIT` | Number of local request traces retained, default 100 and maximum 1000 |\n| `HOST` \u002F `PORT` | Listening interface and port, default `0.0.0.0:3888` |\n\nFor installed CLI starts, `--model` overrides the selected executor's model setting and `--effort` overrides `AI_EFFORT` for that process only. Command-line options and process environment variables take precedence over the selected configuration file.\n\nRun the checks before submitting a change:\n\n```bash\nnpm run check\n```\n\nFor implementation details, see the [architecture notes](docs\u002Farchitecture.md).\n\n## Build it with us\n\nPenEcho is young and built in the open. The problems that matter most — handwriting recognition, on-canvas visual tools, wider model support, and natural pen interaction — are still open, and you do not need to write code to help move them forward.\n\nWays to help:\n\n- **Use it and share what happened.** A canvas that worked well, or one that fell apart, tells us more than any benchmark. A screenshot with secrets removed is enough.\n- **Test a model.** Try any model or provider and report the executor, model ID, effort, rough latency, and a sample result. Google\u002FGemini models are still untested and especially welcome.\n- **Report rough edges.** Recognition misses, layout glitches, and awkward pen behavior are all worth an issue, however small.\n- **Write code.** Recognition, visual tools, model adapters, and pen input each have room to grow. `npm run check` runs the full suite before you open a pull request.\n- **Help more people read it.** The UI ships English and Chinese today; more translations and clearer docs are welcome.\n\nWhere to talk:\n\n- [Discord](https:\u002F\u002Fdiscord.gg\u002F3jrPJ3mXdX) — real-time discussion, model-testing notes, and shared canvas workflows. New faces and works-in-progress are always welcome.\n- [GitHub Discussions](https:\u002F\u002Fgithub.com\u002Ferickong\u002Fpenecho\u002Fdiscussions) — ideas and questions worth keeping searchable.\n- [GitHub Issues](https:\u002F\u002Fgithub.com\u002Ferickong\u002Fpenecho\u002Fissues) — reproducible bugs and confirmed work.\n\nNew contributors start with [CONTRIBUTING.md](CONTRIBUTING.md). If PenEcho clicks for you, star the repo and share the demo — that visibility is what brings the next person in.\n\n## License and commercial use\n\nPenEcho is open source under [GNU AGPL v3.0 only](LICENSE). Commercial use is allowed under the AGPL. If you modify PenEcho and provide that version to users over a network, you must offer those users the corresponding source code as required by the license.\n\nAn alternative [commercial license](COMMERCIAL-LICENSE.md) is available for proprietary products and hosted services that cannot meet the AGPL requirements. The PenEcho name and logo are governed separately by the [PenEcho trademark policy](TRADEMARKS.md).\n\nContributors keep ownership of their work and grant the project the rights needed to offer both AGPL and commercial editions. See the [contributor agreement](CONTRIBUTOR-LICENSE-AGREEMENT.md).\n",2,"2026-07-19 02:30:03","CREATED_QUERY"]