GitHub - penecho/penecho: Think with AI beyond the chat box. A shared canvas for handwriting, equations, diagrams, and spatial reasoning.

English | 简体中文 | 日本語 | 한국어 | Русский | Español | Português (Brasil) | Français | Deutsch

Think with AI beyond the chat box.

PenEcho is a shared canvas where handwriting, equations, diagrams, and spatial context become part of the conversation.

Official Website · penecho.ai

Publish ideas · Collaborate through shared canvases · Share your work

Website • Features • Quick Start • Cloud • Models • FAQ • Architecture • Discord

Kimi Open Source Friends

PenEcho is an official member of Kimi Open Source Friends, Moonshot AI's program supporting outstanding open source projects. The Kimi team backs PenEcho's development with API credits, and Kimi K3 is one of the recommended models for demanding canvas work — accurate on handwriting, strong on diagrams, and fast in practice.

Using these links directly supports the project:

• Kimi Code — Kimi's coding subscription, available worldwide
• Kimi Open Platform · China — API access for mainland China
• Kimi Open Platform · Global — API access for the rest of the world

✨ Features

• Think in space, not in chat. Write a question, equation, diagram, or half-formed idea anywhere on a 20,000 x 20,000 canvas. PenEcho reads your marks and their spatial relationships, then answers beside them.
• Answers on the canvas. Get hints, explanations, formulas, plots, and diagrams where you are working. Move, resize, and copy each AI draft, then accept or discard it before it becomes part of your ink.
• Natural input. Draw with a stylus or mouse; lasso confirmed ink to move, resize, recolor, or delete it, or send just that selection to Typeset. Editing your own ink never triggers an AI request.
• Editable AI widgets. Sandboxed interactive HTML, professional diagrams, animations, and live-data plugins — refinable in place with incremental unified-diff edits instead of full regeneration.
• Multiple AI connections. Save up to ten API or CLI connections with one-click switching, including editable Kimi and MiniMax presets, and pick a different active connection per client.
• Projects and sharing. Organize server canvases into projects, open them from other authorized devices, and export confirmed ink as a cropped PNG.
• PenEcho Cloud. Sign in at penecho.ai to continue private projects on other devices, sync favorites, reach this host remotely through a linked device, and share public Crafts through Echoes — API credentials never leave the device.
• Four themes to match the problem you are exploring: Arcane, Sci-fi, Research, or Studio.

🚀 Quick start

Desktop app — download from GitHub Releases.

npm — needs Node.js 20.3+ and one of: an API key, an authenticated Kimi Code CLI, an authenticated Codex CLI, or an authenticated Claude Code CLI.

npm install -g penecho
penecho configure   # pick your LLM source: API, Kimi, Codex, or Claude CLI
penecho             # then open http://localhost:3888

From source

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

On first start, the initial browser session must set a shared six-digit security code or explicitly acknowledge leaving the process open to the local network. Configuration is saved to ~/.penecho/config.env; API keys never reach browser code. CLI modes require an authenticated CLI on your PATH — see the configuration reference for CLI setup, effort mapping, and every setting.

☁️ PenEcho Cloud

PenEcho Cloud is the companion website and account introduced in 1.0.0. It connects your devices and your work — and it is entirely optional: PenEcho keeps working fully offline with your own API or CLI setup.

On the website you can:

• Sign in with your browser and manage your Cloud account, storage, and credits
• Open Echoes and browse public Canvases and Widgets shared by the community
• View any public Craft in a read-only web viewer and share its link with anyone
• Manage project revisions, Trash, and recovery
• Generate pairing keys under Cloud → Devices to link your PenEcho hosts

In the app, signing in adds:

• Cloud projects. Save private, versioned Canvases into projects and continue them on any signed-in device. Every successful save creates an immutable revision, and a Canvas updated on another device is never silently overwritten — you are asked to load the latest version or save a copy.
• Linked device. Pair this host with a one-time key from Cloud → Devices, and your signed-in browsers and apps can reach it from anywhere through Cloud relay. Remote access to your canvas host without exposing it to the internet; API credentials still live only on that device. Pause, resume, or remove the link at any time.
• Echoes: co-creation and knowledge sharing. Browse public Canvases and Widgets across twelve categories, favorite them into a personal library that syncs through Cloud, and add community Widgets straight into your own Canvas. Publish a Canvas of your own with a share category so others can learn from it, build on it, and Echo it — with Craft lineage preserved between versions.

🔔 What's new in 1.0.0

• PenEcho Cloud is live. Sign in with your browser for private cloud projects, synced favorites, and remote access — API keys stay on your device.
• Cloud projects. Private, versioned Canvases organized into projects, with an immutable revision on every save and safe handling of concurrent edits from another device.
• Linked device. Pair this host with a one-time key so your signed-in browsers and apps can reach it from anywhere; pause, resume, or remove the link at any time.
• Echoes and public Crafts. Browse, favorite, and reuse public Canvases and Widgets across twelve categories, publish your own with a share category, and open any public Craft in a read-only web viewer.
• Personal favorites library. Widget favorites become a personal library with cloud sync — stored locally while signed out, merged into Cloud when you sign in.

0.9.0 added multiple AI connections with one-click switching, project-based shared canvases, guided in-place Refine, unified-diff incremental edits, SSE streaming, and request progress with cancellation. See Releases for the full history.

📖 How it works

The browser sends only the relevant canvas crop and geometry. The server validates the request, routes it to your selected executor, and returns a movable draft that stays separate from confirmed ink until you accept it. PenEcho allocates 512 x 512 tiles only where ink exists, so the huge logical canvas never becomes a huge bitmap. Implementation details are in the architecture notes.

Recommended model configurations

These recommendations balance answer quality against the latency of PenEcho's real canvas workload, based on current hands-on testing; actual response time varies with the provider, canvas complexity, and reasoning behavior.

Typical output usage per request, including hidden reasoning tokens, is roughly 1,000 tokens at low, 3,000 at medium, and 5,000–8,000 at xhigh/max. At a typical low-effort volume (10,000 input / 1,000 output tokens), current standard GPT-5.6 API rates work out to about $0.003–$0.08 per request across Luna, Terra, and Sol; higher effort levels cost more because reasoning tokens are billed as output. Check current OpenAI API pricing before budgeting. CLI modes use the plan you are already signed in with rather than API billing. Google models are untested — if you try Gemini, please share the configuration and results in an issue.

⚙️ Configuration

penecho configure opens an interactive center covering everything: LLM source, model, effort, timeout, response-token limit, image format, request recording, and the listening interface and port. The settings people touch most, also writable in ~/.penecho/config.env:

Use a different config file for one launch with --config ./team.env, or override the model, effort, and port for one process with flags such as penecho --claude --model opus --effort max. The full reference — CLI prerequisites, effort mapping, timeouts, tracing, and every setting — lives in docs/configuration.md.

🔒 Security

• Each start requires a shared six-digit code (stored only as a salted in-memory hash, rate-limited) or an explicit acknowledgement. It is a trusted-LAN guard, not Internet-grade authentication.
• CLI modes start local CLI processes on valid requests: keep them on the local machine or a trusted, directly connected LAN, and never expose them to the public internet or an untrusted reverse proxy.
• For public exposure, place PenEcho behind HTTPS, stronger authentication, rate limiting, and request-size controls.
• Credentials stay in the Node.js process and the config file and are never sent to browser code. Do not publish config files, logs, screenshots, or request traces containing private content.

🗺️ Roadmap

• Multiple AI connections with one-click switching (0.9.0)
• Project-based shared canvases and versioned bundles (0.9.0)
• Better handwriting recognition
• Broader model coverage — Google/Gemini is untested; test reports are especially welcome
• More natural pen interaction and on-canvas visual tools
• More UI translations — English and Chinese today, more welcome

❓ FAQ

Do I need an API key? No. An authenticated Kimi Code CLI, Codex CLI, or Claude Code CLI works too — PenEcho uses the selected CLI locally and never needs an API key for that source.

Which model should I start with? Kimi K3, Claude Opus 4.8 / 5.0, and the gpt-5.6 family are all good first choices — see recommended models.

Is PenEcho free? The app is free and open source under AGPL v3. Model usage is billed by your provider or included in the Codex/Claude plan you sign in with. A typical low-effort request costs a few cents.

Do I need a Cloud account? No. PenEcho works fully locally with your own API or CLI. Signing in to penecho.ai optionally adds private cross-device projects, synced favorites, remote access to this host through a linked device, and public sharing through Echoes.

Where does my data live? Canvases and settings stay on your device or your own PenEcho server. Keys and settings live in ~/.penecho/config.env, and request recording is disabled by default.

Can I use it from a tablet on my LAN? Yes. Startup prints the machine's LAN URLs; open one on the other device and enter the same six-digit code. If it cannot connect, allow the configured TCP port in the host firewall.

🤝 Contributing

PenEcho is young and built in the open, and the problems that matter most — handwriting recognition, on-canvas visual tools, wider model support, and natural pen interaction — are still open. You do not need to write code to help: test a model and report the executor, model ID, effort, latency, and a sample result; share a canvas that worked or fell apart; or report rough edges, however small.

Run npm run check before opening a pull request. Start with CONTRIBUTING.md, and find us on Discord, GitHub Discussions, and GitHub Issues.

📄 License

PenEcho is open source under GNU AGPL v3.0 only; commercial use is allowed under the AGPL. If you modify PenEcho and serve it over a network, you must offer users the corresponding source code. An alternative commercial license is available for products that cannot meet AGPL requirements. The PenEcho name and logo are governed by the trademark policy, and contributors keep ownership of their work under the contributor agreement.