PocketChat is a native, English-language character chat client for PocketBook e-readers, designed around the slow refresh rate and limited input of e-ink devices.
The native interface is built with PocketFrame, a shared monochrome UI library for PocketBook InkView applications.
The PocketBook stores all characters, conversations, settings, and compact relationship memories locally. It only contacts another device when generating a reply or refreshing a relationship memory.
- Native InkView interface with no browser or JavaScript runtime.
- High-contrast, animation-free layout.
- Touch controls and physical page-key scrolling.
- Partial black-and-white refreshes while scrolling.
- System keyboard for messages and text fields.
- Local characters and one separate persistent chat file per character.
- On-device character creation, editing, and deletion.
- Two-step confirmation for deleting a character or starting a new chat.
- Automatic compact relationship memory when reopening a changed conversation.
- Configurable number of recent messages sent verbatim.
- Multiple consecutive reply bubbles using
<NEXT_MESSAGE>. - Native Ollama
/api/chatsupport. - OpenAI-compatible
/v1/chat/completionssupport for OpenAI, LM Studio, llama.cpp servers, vLLM, LocalAI and similar services. - Optional bearer API key.
- Safe
.pocketcharZIP import with optional character photos. - External Katniss Everdeen and blank-layout example packages.
Place the compiled application here:
/mnt/ext1/applications/PocketChat.app
On first launch it creates:
/mnt/ext1/applications/PocketChatData/
├── settings.conf
├── characters/
│ └── katniss-everdeen.character
└── chats/
└── katniss-everdeen.chat
Files use an intentionally simple, line-based format so they can be backed up and edited over USB without special software. Newlines and tabs inside values are escaped.
Copy .pocketchar files to:
/applications/PocketChatData/import/
PocketChat scans this directory when it starts. You can also select
Import characters in Settings. Successfully processed packages are moved
to PocketChatData/imported/; invalid packages remain in import/ so they can
be corrected.
Every successful character save also atomically refreshes:
PocketChatData/exports/<character-id>.pocketchar
The local .character file is updated first. PocketChat then writes the export
to a temporary ZIP and replaces the previous package only after the new one is
complete. The character editor also provides a manual Export icon.
A .pocketchar file is a ZIP archive containing character.json and,
optionally, photo.jpg, photo.jpeg, or photo.png. Duplicate IDs are
imported as numbered copies instead of overwriting existing characters.
The build output includes PocketChatImports/katniss-everdeen.pocketchar and
PocketChatImports/blank-character.pocketchar. Katniss is not embedded or
hardcoded in the executable.
Open Settings inside PocketChat.
On the computer hosting Ollama, allow LAN connections:
OLLAMA_HOST=0.0.0.0:11434 ollama serveThen configure PocketChat:
Provider: Ollama
Endpoint: http://192.168.1.10:11434
Model: llama3.2
Replace the IP address with the LAN address of the Ollama computer. Permit TCP port 11434 in that computer's firewall. Do not expose an unauthenticated Ollama port directly to the public internet.
Configure:
Provider: OpenAI compatible
Endpoint: https://api.openai.com
Model: your-model-name
API key: your key
The endpoint may include /v1; PocketChat handles both forms. For a local LM Studio server, an example endpoint is http://192.168.1.10:1234/v1.
API keys are stored as plain text on the PocketBook. Use a restricted key and treat the device storage as sensitive.
For each request PocketChat sends:
- the common prompt;
- the complete selected character profile and character-specific prompt;
- the compact relationship memory, when available;
- the configured number of most recent message bubbles.
The default is 30 recent bubbles. Older messages remain stored on the PocketBook but are represented to the model by the relationship memory. Starting a new chat deletes both the message file and that memory.
When a chat is opened, PocketChat refreshes the memory only if new messages have been added since its previous summary. This avoids unnecessary network calls and long e-ink wait screens.
- Tap a character to open its chat.
- Tap Write or press the center/OK key to compose.
- Use page or up/down keys to move through long chats and lists.
- Tap New twice to erase the current chat.
- Use + Character to create a profile.
- In the character editor, tap fields to open the system keyboard.
- Open Settings to change provider, server, model, prompt, context and generation parameters.
The supplied reproducible build targets the PocketBook Verse Pro (B300) with firmware SDK 6.8, matching the setup used by PocketOPDS.
Clone the repository with its PocketFrame dependency:
git clone --recurse-submodules https://github.com/T3XMK2/PocketChat.gitFor an existing clone, run git submodule update --init --recursive first.
On Windows, start Docker Desktop and run:
.\build.ps1The first build downloads the approximately 540 MB B300 SDK into Docker's storage. Later builds reuse that image. To force a clean SDK image rebuild:
.\build.ps1 -RebuildWhen drive D exists, the result is:
D:\PocketChatBuild\PocketChat.app
Otherwise it is written to build/PocketChat.app inside the project.
Copy that file to the device:
/mnt/ext1/applications/PocketChat.app
If disk space on the system drive is limited, set Docker Desktop's disk image location to a folder on another drive before the first build.
Storage and JSON handling can be tested without the PocketBook SDK:
cmake -S . -B build-test -DPOCKETCHAT_DEVICE=OFF -DPOCKETCHAT_TESTS=ON
cmake --build build-test
ctest --test-dir build-test --output-on-failureSee DESIGN.md for architecture, performance choices, data ownership, server compatibility, and planned improvements.