tokenicode

TOKENICODE uses Zustand for state management, distributed across several specialized stores. Some stores are persisted (e.g., to localStorage or disk), while others are transient.

Tab-Switching Pattern: The chatStore and agentStore implement saveToCache(tabId) and restoreFromCache(tabId) to allow seamless switching between different chat sessions/tabs.

Session grouping in Tokenicode utilizes @dnd-kit with PointerSensor to handle three specific drag-and-drop scenarios:

1. Reordering within a group: Moving sessions up or down within a single group.
2. Moving sessions between groups: Dragging a session from Group A to Group B.
3. Reordering groups: Moving entire groups up or down.

Technical Implementation Details

• Sensor Choice: The system uses PointerSensor (based on pointerdown, pointermove, and pointerup events) instead of the HTML5 Drag and Drop API. This is critical because the Tauri WKWebView environment intercepts HTML5 drag events (dragstart, dragover, drop) when dragDropEnabled is set to true.
• Coexistence with File Tree: Tokenicode maintains two separate drag-and-drop mechanisms that do not interfere with each other:
  • Pointer-based (dnd-kit): Manages sessions and groups.
  • Mouse-based (custom drag-state.ts): Manages file tree interactions (e.g., dragging a file into a folder or the chat box).
• Testing Strategy: Because simulating pointer events in jsdom is difficult, testing focuses on verifying the mapping between dnd-kit's onDragEnd event and the corresponding groupStore actions using pure function unit tests.

TOKENICODE implements session grouping (Groups) using metadata mapping (tags) rather than physical subdirectories. This design ensures that moving a session between groups is a lightweight operation that does not break the underlying Claude Code session files.

Key Concepts

• No File Movement: Session .jsonl files are never moved from their original Claude Code storage location (~/.claude/projects/<cwd_encoded>/<uuid>.jsonl).
• Metadata-driven: Grouping information is stored in a dedicated TOKENICODE configuration file: ~/.tokenicode/groups.json.
• Hierarchy: The UI renders a three-level hierarchy: Workspace › Group › Session.

Benefits for Users

• Safe Reorganization: You can freely drag and drop sessions to change groups without breaking the resume functionality or losing session continuity.
• Context Inheritance: Because the physical directory (CWD) of the session does not change, sessions correctly inherit the CLAUDE.md and other context files from their original workspace.
• Exporting for Finder: Since groups are not real folders, you cannot browse them directly in Finder. Instead, use the Export feature to copy a group's sessions into a real folder structure (with readable filenames and Markdown) for external use.

Tokenicode organizes Claude Code sessions into a three-tier hierarchy. Understanding the distinction between these levels is critical for managing files and organization:

1. Project (工作区): The top-level (Level 1) organization. These are automatically created by the Claude Code engine based on the session's current working directory (cwd). They correspond to real directories under ~/.claude/projects/ on disk.
2. Group (组): The middle-level (Level 2) organization. These are logical tags manually created by the user to collect sessions. Groups do not correspond to real directories on disk. A Group belongs to a specific Project, and a Session can only belong to one Group at a time (moving a session to a new group removes it from the old one).
3. Session (会话): The bottom-level (Level 3) unit. A single continuous conversation with Claude, which is stored as a .jsonl file.

Tokenicode operates by bridging a React frontend with a Rust backend that manages a Claude Code CLI process via NDJSON (Newline Delimited JSON) streams over IPC.

New Message Flow

1. Input: User submits a prompt via the InputBar.
2. Session Start: The frontend calls bridge.startSession with parameters like prompt, cwd, model, thinking_level, permission_mode, and provider_id.
3. CLI Execution: The Rust backend spawns the CLI process using stream-json I/O.
4. Stream Processing: A stdout reader parses NDJSON. It intercepts control_request events and forwards the rest of the stream.
5. UI Update: The useStreamProcessor hook parses claude:stream events and updates the chatStore. React then re-renders the ChatPanel.

Follow-up Messages

For persistent sessions, the frontend uses bridge.sendStdin(sessionId, message). The StdinManager writes NDJSON to the existing CLI process's stdin, following the same stream processing pipeline.

TOKENICODE allows you to connect to third-party AI model providers (like DeepSeek, SiliconFlow, or Moonshot) by manually entering their API credentials. This is useful for accessing different models, pricing tiers, or regional providers.

Configuration Requirements

To add a provider, you need the following information from your chosen provider's dashboard:

1. Name: A label for your own reference (e.g., CloudMist AI).
2. Base URL: The API endpoint address provided by the service (e.g., https://yunwu.ai/v1).
3. API Key: Your unique authentication token, typically starting with sk-.
4. Protocol Type: Most modern providers use the OpenAI 兼容 (OpenAI compatible) protocol.

Setup Steps

1. Open TOKENICODE and click the Settings icon (⚙️) in the left sidebar.
2. Locate the API 提供商 (API Provider) or 自定义 API (Custom API) section and click 添加 (Add).
3. Fill in the required fields (Name, Base URL, API Key, and Protocol Type).
4. Click 保存 (Save) or 测试连接 (Test Connection).

Troubleshooting Connection Failures

| 字段 | 填什么 | 说明 |
|------|--------|------|
| 名称 | 随便起，比如「云雾AI」 | 只是给你自己看的标签 |
| Base URL | `https://yunwu.ai/v1` | 第四步找到的地址 |
| API Key | 刚才复制的 `sk-xxx...` | 第三步拿到的密钥 |
| 协议类型 | OpenAI 兼容 | 大多数供应商都选这个 |