PinchChat

PinchChat is built using a modern web stack designed for high-performance chat interfaces and real-time streaming:

• Framework: React 19 + TypeScript
• Build Tool: Vite
• Styling: Tailwind CSS v4 using CSS custom properties for theming
• Icons: Lucide React
• Markdown Rendering: react-markdown with rehype-highlight and remark-gfm support
• State Management: Native React hooks and contexts (no external state libraries like Redux or Zustand)

PinchChat is designed to provide a high-visibility, chat-centric interface for interacting with AI agents. Its core value propositions include:

• Tool Call Visualization: Real-time visibility into agent actions via color-coded badges, expandable parameters, and visible results.
• GPT-like Interface: Familiar session management in a sidebar, allowing easy switching between conversations.
• Real-time Token Usage: Visual progress bars per session to monitor remaining context/token limits.
• Live Streaming: Real-time observation of the agent's thinking process and text generation.
• Multi-session Support: Navigation across all active sessions, including crons and sub-agents.
• Inline Media: Direct rendering of images (png, jpg, gif, webp) within the chat and tool results.
• i18n Support: Switchable languages (English/French).

Theming in PinchChat is handled via CSS custom properties defined in ThemeContext. Instead of hardcoded colors, components use Tailwind utility classes that reference these variables (e.g., text-pc-text, bg-pc-elevated).

Available Themes:

• Dark (default)
• Light
• OLED Black
• System (follows OS preference)

Available Accent Colors:

• Cyan, Violet, Emerald, Amber, Rose, Blue

PinchChat uses color-coded badges to help users visually identify the type of tool an agent is executing. These badges include emojis to improve recognition:

• 🔍 web_search (Emerald)
• ⚡ exec (Amber)
• 📖 read (Sky)
• ✏️ write/edit
• 🌐 browser
• 🖼️ image
• 🧠 memory
• ⏰ cron
• 🚀 sessions_spawn

To manage high token usage and free up context window space, you can trigger a context compaction via the PinchChat UI. This process summarizes older messages in the conversation history.

Technical Details:

• The UI triggers the sessions.compact API call.
• It requires the operator.admin scope.
• The compaction process typically truncates transcript files that exceed 400 lines.
• Note: Ensure your session has sufficient history; compaction may not appear to trigger if the session history is below the threshold.

The PinchChat sidebar uses specific icons to identify the type of channel or session being viewed:

• Discord: Discord icon
• Telegram: Telegram icon
• Cron: Clock or gear icon
• Webchat: Chat/bubble icon
• Other (e.g., TeamSpeak): Generic bubble or globe icon

The codebase is organized as follows:

• src/App.tsx: The root component handling the login gate, layout, and lazy-loading the Chat component.
• src/main.tsx: The application entry point.
• src/types.ts: Shared TypeScript definitions (e.g., Session, Message).
• src/components/: All React UI components.
• src/hooks/: Custom React hooks (e.g., useGateway, useTheme).
• src/lib/: Pure utility modules that do not depend on React.
• src/contexts/: React contexts for global state like themes and UI collapse states.

PinchChat is a client-side application that communicates with an OpenClaw Gateway via WebSockets.

Core Components

• useGateway.ts: The central hook managing the WebSocket state machine (auth, sessions, messages).
• LoginScreen.tsx: Handles runtime credential entry.
• Chat.tsx & ChatMessage.tsx: Manage message rendering, including markdown, tool calls, and thinking blocks.
• Sidebar.tsx: Manages session navigation and token usage visualization.

Data Flow

1. Login: User enters gateway URL + token $\rightarrow$ stored in localStorage.
2. Connect: useGateway opens a WebSocket and authenticates.
3. Sessions: Gateway pushes the session list; user selects one in the sidebar.
4. Messages: Messages stream in via WebSocket frames; the hook assembles partial chunks into complete messages.
5. Send: User input is sent as a JSON frame over the WebSocket.

To run PinchChat from source, you need Node.js 20+ and an accessible OpenClaw gateway.

1. Clone the repository.
2. Install dependencies using npm install.
3. Create a .env file from the example.
4. Start the development server with npm run dev.

You can pre-fill the gateway URL in your .env file using VITE_GATEWAY_WS_URL.

git clone https://github.com/MarlBurroW/pinchchat.git
cd pinchchat
npm install
cp .env.example .env
npm run dev

The recommended way to run PinchChat is using Docker. You can run a single container or use Docker Compose.

Single Container: Run the following command to start the container and map port 3000 to the container's port 80.

Docker Compose: Download the provided docker-compose.yml and run it with docker compose up -d.

Once running, open http://localhost:3000 in your browser and enter your OpenClaw gateway URL and token on the login screen.

# Run single container
docker run -p 3000:80 ghcr.io/marlburrow/pinchchat:latest

# Or use Docker Compose
curl -O https://raw.githubusercontent.com/MarlBurroW/pinchchat/main/docker-compose.yml
docker compose up -d

To build the project from source, ensure you are using Node.js 20+. If you encounter errors, perform a clean install:

# Ensure Node.js 20+
node --version

# Clean install
rm -rf node_modules package-lock.json
npm install
npm run build