Chatons User Guide
This guide covers what you can do in Chatons today. No implementation details -- just product behavior.
Scope baseline: current behavior observed in the codebase as of March 10, 2026.
1. Startup
When Chatons starts, it shows a loading screen with:
- A centered mascot video (
chaton-hero.webm) - Rotating cat-themed loading messages
- Fade transitions between messages
The loading screen is displayed until workspace hydration completes. This prevents a blank or half-initialized UI.
2. First Launch (Onboarding)
On first launch, Chatons opens a two-part onboarding flow.
Intro Slideshow
Before setup, a short 4-slide intro explains what Chatons does:
- Slides advance with Next/dots navigation
- A "Skip intro" button skips to setup
- The mascot video stays visible throughout
Step 1: Provider Setup
Choose a provider preset card (OpenAI, ChatGPT, Mistral, Ollama, LM Studio, etc.) and configure:
- API type (OpenAI completions, responses, or Codex)
- Base URL (auto-corrected for common variants like missing
/v1) - API key (optional for local providers like Ollama)
Provider cards are grouped by company. For example:
- OpenAI group shows: "OpenAI" (API key, standard endpoint) and "ChatGPT" (OAuth,
chatgpt.combackend) - Mistral group shows: "Mistral" (
api.mistral.ai/v1) and "Mistral Vibe" (vibe.mistral.ai/v1)
Clicking a provider card scrolls to the configuration form automatically.
Local Provider Detection
Chatons can auto-detect local providers:
| Provider | Detection | API Check | Default Base URL |
|---|---|---|---|
| Ollama | command -v ollama (Unix) / where ollama (Windows) | GET http://127.0.0.1:11434/api/tags | http://localhost:11434/v1 |
| LM Studio | Checks for app installation path per platform | GET http://127.0.0.1:1234/v1/models | http://localhost:1234/v1 |
LM Studio app paths checked: /Applications/LM Studio.app (macOS), %LOCALAPPDATA%\Programs\LM Studio (Windows), ~/LM-Studio or ~/Applications/LM-Studio (Linux).
VS Code is also detected (via which code / where code) for the worktree "Open in VS Code" feature.
Step 2: Model Scope
Chatons loads available models from your provider and asks which ones you want in your everyday model picker. These become your "scoped" models.
Step 3: Validation
A basic check verifies your setup works before enabling the main interface.
Re-opening Onboarding
Cmd+Shift+O(macOS)Ctrl+Shift+O(Windows/Linux)
3. App Modes
Chatons has two modes, switchable via a toggle at the bottom of the sidebar:
| Mode | Icon | Purpose |
|---|---|---|
| Workspace | Monitor | Conversations, projects, coding |
| Assistant | Cat | Dashboard, memory, automations, channels overview |
The mode switcher is always visible below the sidebar content.
4. Assistant Mode
Assistant mode provides a high-level overview of your AI assistant's activity.
Assistant Onboarding
On first entry, assistant mode shows its own onboarding flow (separate from provider onboarding):
- Welcome screen -- Explains the assistant concept
- Step 1: Channel -- Select or install a channel extension (e.g. Telegram). Optional; can be skipped.
- Step 2: Personalize -- Set a name for the assistant (default: "Chaton") and optionally your own name
- Step 3: Complete -- Confirmation
Dashboard
After onboarding, the assistant dashboard shows:
- Greeting -- Time-based greeting ("Good morning", etc.) with your name if set
- Status indicator -- Online (green dot) if any channel is connected; offline (gray dot) otherwise
- Quick actions -- 4 buttons: Talk to assistant, Schedule task, View memory, Settings
- Channel status -- List of installed channels with connection state and config buttons
- Recent activity -- 5 most recent conversations with relative timestamps, clickable to open
- Memory insights -- Preview of the 5 most recent global memories with a "View all" link
- Automations summary -- List of automation rules with triggers, and a link to manage
Assistant Sidebar
In assistant mode, the sidebar navigation changes to:
| Entry | View |
|---|---|
| Home | Dashboard |
| Conversations | Switches back to workspace mode |
| Memory | Full memory browser |
| Automations | Full automation rules browser |
| Channels | Channel extensions list with configure buttons |
5. Workspace Mode
Workspace mode is the default. This is where conversations, projects, and coding happen.
Left Sidebar
Navigation items:
- New thread -- Create a global conversation
- Automations -- Open the automation rules screen
- Skills -- Manage Pi skills
- Extensions -- Manage installed extensions
- Channels -- Appears when a channel extension is installed and enabled
- Settings -- App settings
Below the navigation:
- Thread and project list with search (toggle via the search icon)
- Sort/filter/organize options (via a popover)
- Update availability and changelog cards (outside dev mode)
Conversation List Management
A sort/filter popover (accessible from the sidebar header) provides three controls:
| Control | Options | Default |
|---|---|---|
| Organize | By project (grouped under project headers) / Chronological (flat list) | By project |
| Sort by | Created / Updated | Created |
| Show | All conversations / Relevant only | All |
Additionally, a search bar (toggled by the search icon) lets you filter conversations by title text.
Main Panel
Displays one of:
- Conversation timeline
- Settings pages
- Skills catalog
- Extensions management
- An extension's main view (e.g. Automation)
Extension main views use the full width and height of the main panel, not the narrower conversation column.
Empty threads show quick action cards and a "Start the conversation" banner. These disappear after the first exchange.
Composer (Bottom)
The composer handles:
- Text input with attachments
- Model picker (scoped models shown first, "more" to see all)
- Thinking level selector (when the model supports it)
- Access mode toggle (secure / open)
- Queued message indicator
- Thread-scoped file modifications summary
The composer and its toolbar use translucent backgrounds with blur so conversation content remains subtly visible behind them.
6. Conversations
Create a Global Thread
Click New thread in the sidebar or the + button in the topbar.
Import a Project
Click Add project in the sidebar and select a folder. If it is not already a Git repository, Chatons initializes one automatically.
Create a Project Thread
Inside a project group in the sidebar, click the compose icon to create a thread linked to that project.
Delete Threads and Projects
Deletion uses a two-click confirmation pattern for safety.
7. Model Picker
The model chip in the composer opens the model picker:
- Default view: Shows scoped (starred) models only
- "More" action: Reveals all available models with a text filter
- Star/unstar: Click the star to add or remove a model from your scoped set
Starring and unstarring updates the actual Pi configuration (settings.json > enabledModels), not just UI state. This is consistent across onboarding, settings, and the composer.
8. Thinking Level
If the selected model supports reasoning/thinking levels, a thinking-level chip appears next to the model picker in the composer.
Available Levels
Models may support any subset of: off, minimal, low, medium, high, xhigh. The chip only appears if the model advertises at least one thinking level.
Behavior
- Click the chip to open a dropdown with available levels
- The selected thinking level is stored per conversation
- Changing the thinking level does not restart the runtime
9. Access Mode
Each conversation has an access mode:
- Secure: The AI can only access files within the project directory (or global workspace for non-project threads)
- Open: The AI has full filesystem and command access
A comparison popup explains when to use each mode. Changing the access mode on an existing thread restarts that conversation's runtime. Any technical runtime bookkeeping messages related to that switch stay hidden from the conversation view.
10. Sending Messages
While the AI Is Working
If the AI is processing or the runtime is still starting, pressing send queues your message instead of dropping it. The send button shows a queue icon during this state. Queued messages are visible and editable.
Stop Button
A stop button appears while the AI is processing. Click to cancel the current execution.
Attachments
Add files via the + button or drag-and-drop:
- Images: Sent as image payloads
- Small text files: Included as readable text
- Binary/large files: Included as base64 preview
Composer Drafts
Typed text in the composer is automatically saved to the database per conversation (or per project for draft threads). Drafts survive app restarts. When you switch between conversations, your unsent text is preserved and restored.
11. Suggested Thread Actions
The AI can suggest up to 4 clickable action badges above the composer. These are ephemeral:
- Click one to prefill the composer with that action
- Send any message and the badges clear
12. Live File-Change Tracking
When a conversation modifies files, Chatons shows a modifications panel above the composer with:
- Changed files count
- Added/removed line counts
- Inline per-file diffs
- Navigation between changes
Changes are thread-scoped deltas (relative to the thread start baseline).
Timeline Diff Rows
After tool executions, the conversation timeline shows compact file-change summaries:
Modified path/to/file.ts +12 -3Click a row to expand the inline diff. These are incremental -- each row shows only files changed since the previous tool execution snapshot. Pure Git state transitions (like staging/committing without content changes) are not surfaced as new rows. Only changes associated with recent edit tool executions in the same thread are shown.
13. Worktree Mode
For project threads, worktree mode is disabled by default.
Enable Worktree
Click the branch icon in the topbar. The icon turns green when active. Click again to disable.
Worktree Actions
When enabled, a "Manage worktree" dialog provides:
- Worktree status inspection
- AI-generated commit message suggestion based on current staged and unstaged diffs
- Commit
- Merge to the detected default base branch
- Push
- Open in VS Code (if detected)
Limitations
- Some worktree metadata is approximate
- Ahead/behind counts are not authoritative in all cases
- Push may be unavailable in some configurations
- Automatic merge requires native Git; when unavailable, Chatons shows the limitation instead of attempting a synthetic merge
14. Project Terminal
For project conversations, a terminal button opens a command runner dialog.
Command Detection
Chatons detects runnable commands based on project files:
| File | Project Type | Commands Detected |
|---|---|---|
package.json | Node | npm run start/dev/test/build/lint/preview |
manage.py | Python | python manage.py runserver |
app.py / main.py | Python | python app.py / python main.py |
Cargo.toml | Rust | cargo run, cargo build, cargo test |
go.mod | Go | go run ., go build, go test ./... |
Makefile / CMakeLists.txt | C/C++ | make, cmake --build . |
You can also run custom commands.
How It Works
- Commands run in the host environment (not through the Pi runtime)
- Output is streamed live to a popup
- Multiple runs display as tabs
- Requires open access mode
- This is a managed process runner, not an interactive PTY terminal
15. Automations
The Automations sidebar entry opens a dedicated screen where you can:
- List existing automation rules
- Create new rules with trigger, action, cooldown, and instruction
- View recent execution history
- Delete rules (double-click)
- Ask the AI to create an automation during a conversation
See Automation Extension for technical details.
16. Skills
The Skills panel manages Pi skills -- tools that extend the AI's capabilities during conversations.
Two Views
| View | Purpose |
|---|---|
| Marketplace | Browse, search, filter, and install skills |
| Installed | Manage skills you have already installed |
Marketplace
The marketplace organizes skills into sections:
- Featured (curated selection)
- Recently Added (new skills)
- Trending (popular and recommended skills)
- By Category (AI & ML, Web & APIs, Code Quality, Version Control, Testing & Debug, CI/CD & Deployment)
Filtering
Click the Filters button (or Ctrl/Cmd+F) to open the advanced filter panel:
| Filter | Options |
|---|---|
| Category | AI & ML, Web & APIs, Code Quality, etc. |
| Language | TypeScript, Python, JavaScript, Go, Rust, Bash |
| Min. installations | Numeric threshold |
| Sort by | Trending, Installations, Stars, Recent, Rating |
Skill Preview
Click Preview on any skill card to see:
- Full description
- Documentation and repository links
- Dependencies
- Category and language
- Install/star counts
- Community ratings with star display
Ratings
Users can rate skills (1-5 stars) with an optional text review. Average ratings and review counts are shown on skill cards and in the preview.
Keyboard Shortcuts
| Shortcut | Action |
|---|---|
Ctrl/Cmd+K | Focus search bar |
Ctrl/Cmd+F | Toggle filters panel |
Skills are managed through the Pi runtime, not through the Chatons extension system.
17. Extensions
The Extensions panel manages Chatons extensions -- more powerful integrations than skills, with UI, storage, events, and host API access.
Three Views
| View | Purpose |
|---|---|
| Marketplace | Browse, search, and install extensions |
| Installed | Manage installed extensions: enable, disable, remove, view logs |
| Updates | Shows extensions with available updates |
Marketplace
Like skills, the extension marketplace shows featured, new, trending, and categorized extensions. Each card shows the extension name, description, author, and install/update actions.
Update Notifications
When extension updates are available:
- A badge with the update count appears on the Extensions sidebar entry
- The Updates view lists all updatable extensions with version numbers
- An Update All button applies all updates at once
Extension Actions
For installed extensions:
- Enable/disable toggle: Enables or disables the extension
- Remove: Uninstalls the extension
- View logs: Shows runtime logs from the extension
- Health check: Runs and displays the health status
- Server status: Shows whether the extension server is ready (for extensions with servers)
- Publish: Publish to npm (requires stored npm token)
Deep Link Install
Opening a chatons://extensions/install/@scope/package-name URL triggers the extension marketplace to scroll to and highlight the matching extension.
Channels
Some extensions act as messaging bridges (e.g. Telegram). These are identified by kind: "channel" in their manifest. When at least one channel extension is enabled, a Channels entry appears in the sidebar. Inbound channel messages create global threads only, not project threads.
Built-in extensions such as @chaton/automation, @chaton/memory, @chaton/ide-launcher, and @chaton/tps-monitor are bundled with the app and do not appear in the user extensions folder.
18. Memory
The built-in Memory extension stores context that persists across conversations.
Scopes
- Global: Personal preferences, facts, and user context (applies across all projects)
- Project: Project-specific conventions, decisions, and architecture notes
How It Works
- The AI can store, search, update, and delete memories during conversations
- Uses a lightweight local semantic search (hashed trigram vectors) -- no external embedding service needed
- Stored in the local SQLite database
Use Cases
- Remember your preferred language or coding style
- Remember project architecture decisions
- Store recurring instructions the AI should follow
Automation Suggestions
Chatons can notice when you ask for the same kind of useful task repeatedly and suggest turning it into an automation.
- Suggestions are reserved for recurring patterns, not one-off requests
- Chatons only suggests patterns it has a built-in path to automate
- Suggestions are throttled so they should not appear frequently
- Clicking a suggestion now opens the automation form with a prefilled draft for review
19. Settings
Available settings sections:
| Section | What It Controls |
|---|---|
| General | Theme (system / light / dark) |
| Audio | Conversation completion chime (enabled by default) |
| Behaviors | Default behavior prompt prepended to every conversation |
| Sidebar | Sidebar display options, anonymous telemetry toggle |
| Language | French / English (default: French, fallback: English) |
| Providers & Models | Provider configuration and model scoping |
| Sessions | Open the sessions folder |
| Pi | Pi command output panel |
| Diagnostics | Runtime paths and checks |
Audio
Chatons plays a short chime sound when a conversation action completes. This can be toggled in Settings > Audio. The chime has a 1.5-second cooldown to prevent rapid-fire playback. Volume is fixed at 24%.
Language
The app ships with French and English translations. The default language is French with English as the fallback. Language preference is stored in the database and persists across sessions.
20. Telemetry Consent
After onboarding, a consent card may appear in the bottom-right:
- Allow: Enables anonymous crash/error telemetry (via Sentry)
- No thanks: Keeps telemetry disabled
The setting is persisted and can be changed later in Settings > Sidebar.
Telemetry is never initialized in development mode.
21. macOS Window Behavior
On macOS, closing the window does not quit Chatons. The app continues running in the background with a status bar icon.
- Close window (red dot): Hides the window
- Quit (menu bar or
Cmd+Q): Actually quits the app - Click status bar icon: Shows the window again
On all platforms, closing all windows keeps the app running in the background.
22. Updates and Changelog
Outside development mode:
- Update availability is shown in the sidebar
- Download progress is displayed
- A changelog card appears for new versions
- On macOS, applying an update opens the downloaded DMG in Finder
- If the changelog is unavailable locally, a built-in fallback is shown
- If no installer has been downloaded yet, a helpful message is shown instead of failing
23. Deep Links
Chatons registers the chatons:// protocol. Currently supported:
chatons://extensions/install/@scope/package-nameThis opens Chatons and triggers the extension install flow.
24. Notifications
When the app window is not focused, Chatons shows desktop notifications when conversation actions complete. Clicking a notification brings the window to the foreground.
25. Keyboard Shortcuts
| Shortcut | Action |
|---|---|
Cmd+Shift+O / Ctrl+Shift+O | Re-open onboarding |
Cmd+Q | Quit (macOS) |
Ctrl/Cmd+K | Focus skills search bar (in Skills panel) |
Ctrl/Cmd+F | Toggle skills filters panel (in Skills panel) |
Enter | Send message (in composer) |
Shift+Enter | New line (in composer) |
26. Known Limitations
- Worktree push may not work in all environments
- Extensions require an app restart after install to fully load
- OAuth tokens are not auto-refreshed when they expire -- re-authenticate via Settings > Providers & Models
- The project terminal is a process runner, not an interactive shell
- Model/skills/settings commands use the internal Pi runtime, not a user-global
~/.piinstall