# Fusuma — Complete Reference

> An all-in-one agent harness that brings AI chat, terminal, browser, and file management into one seamless grid layout. Built with Tauri, React, and Rust by Koi Fish Labs.

## Overview

Fusuma (襖, Japanese for "sliding partition") is a local-first, all-in-one agent harness for software developers who work with AI coding assistants. Rather than switching between a terminal, browser, IDE, and AI chat window, Fusuma combines all of these into a single native macOS window with a drag-and-drop widget grid.

The name comes from the traditional Japanese sliding doors that partition rooms — Fusuma partitions your workspace into configurable panels.

- **Platform**: macOS 13+ (Apple Silicon, M1 or later)
- **Stack**: Tauri v2 (Rust backend), React + TypeScript (frontend), Tailwind CSS
- **Current version**: 1.0.42
- **Price**: Free
- **Binary size**: <15MB
- **Cold start**: <1 second
- **Website**: https://fusuma.dev
- **Developer**: Koi Fish Labs

---

## Widget Types

Fusuma provides six widget types that can be freely arranged in the grid:

### 1. AI Chat Widget
- Supports multiple AI providers: Claude (Anthropic) and Codex (OpenAI)
- Each widget connects to a separate AI session — run multiple AI chats side by side
- AI agents execute via locally installed CLI tools (Claude Code CLI, Codex CLI)
- Fusuma does NOT proxy AI traffic through its own servers — prompts go directly from the CLI tool to the AI provider
- Permission modes: manual approval, suggest, or full-auto
- Agents can read project files, execute terminal commands, and browse the web
- Custom system prompts per widget
- Model selection (e.g., claude-opus-4-6, claude-sonnet-4-6)
- Streaming responses with live output

### 2. Terminal Widget
- Full PTY (pseudo-terminal) emulation via native Rust backend
- Runs the user's default shell (zsh, bash, etc.)
- ANSI color support, link detection
- Persistent sessions across app restarts
- Multiple terminal instances in separate widgets

### 3. Browser Widget
- Embedded Chrome browser via Chrome DevTools Protocol (CDP)
- Renders real web pages inside the workspace — not a separate window
- AI agents can programmatically open URLs, take screenshots, navigate tabs
- Local CDP connection (WebSocket), no cloud dependency

### 4. File Explorer Widget
- Two view modes: tree view (hierarchical) and card view (visual grid)
- Drag-and-drop files into AI chat to provide context
- Full-text search with instant filtering
- Inline preview for code, images, PDFs, video, and more
- Git status indicators (modified, added, untracked badges)
- File type icons with color coding

### 5. Git & Diff View Widget
- Visual diff display with side-by-side comparison
- Minimap visualization for large diffs
- Stage, unstage, commit, and checkout operations from the UI
- Shows staged and unstaged changes at a glance

### 6. Widget Grid Layout
- Snap-to-grid drag-and-drop layout engine
- Horizontal and vertical splitting
- Resize any widget by dragging edges
- Swap widget positions by dragging
- Layouts persist per workspace across sessions
- Add/remove widgets dynamically

---

## Workspaces

- Each workspace points to a project directory on disk
- Workspaces maintain independent widget layouts, AI sessions, and terminal states
- Switch between workspaces with keyboard shortcuts (Cmd+1, Cmd+2, etc.)
- Toast notifications appear when AI tasks complete in background workspaces
- Workspace metadata stored locally at ~/.kagura/workspaces.json

---

## AI Integration Details

### How AI Works in Fusuma

Fusuma does NOT include its own AI model or API key management. Instead, it delegates to CLI tools the user has already installed:

1. **Claude Code** (`claude` CLI by Anthropic) — the primary supported agent
2. **Codex CLI** (`codex` by OpenAI) — alternative agent support

When a user sends a message in an AI chat widget:
1. Fusuma spawns a local shell process
2. Executes the CLI tool with the user's prompt via stdin
3. Streams the AI response from stdout back to the UI
4. The CLI tool handles authentication and API calls to the AI provider directly

This means:
- Fusuma never sees or stores API keys
- AI conversations never pass through Fusuma's servers
- The AI provider's own privacy policy governs conversation data
- Users need their own Claude Code or Codex CLI subscription

### Permission Modes

AI agents can perform actions on the user's machine. Fusuma provides three permission levels:
- **Manual**: User must approve every file read, command execution, or web action
- **Suggest**: Agent suggests actions, user confirms with one click
- **Full-auto**: Agent executes actions automatically without confirmation

### MCP (Model Context Protocol)

Fusuma supports MCP server integration, allowing AI agents to connect to external tools and data sources through standardized protocols.

### Skills

Reusable prompt templates that give AI agents project-specific knowledge and capabilities.

---

## Architecture & Performance

### Local-First Design
- All user data stays on the local machine
- No cloud sync, no remote storage of projects or code
- Workspace configs, agent logs, and preferences stored locally
- Internet required only for: OAuth sign-in, crash reporting, auto-updates, and AI provider API calls (via CLI)

### Tech Stack
- **Frontend**: React 19 + TypeScript, Tailwind CSS, Zustand (state management)
- **Backend**: Rust, compiled as a native Tauri v2 application
- **Terminal**: Native PTY implementation in Rust
- **Browser**: Chrome DevTools Protocol over local WebSocket
- **Build**: Vite (dev server with HMR), pnpm (package manager)

### Performance
- Binary size: <15MB (vs. 200MB+ for typical Electron apps)
- Cold start: <1 second
- Memory usage: <30MB baseline
- Hot reload: Vite HMR for frontend, cargo watcher for Rust backend

---

## Data & Privacy Summary

### What Fusuma Collects (Server-Side)
1. **OAuth account info**: Name, email, profile image from GitHub or Google sign-in
2. **Session metadata**: IP address, user agent, session timestamps
3. **Crash reports**: Error messages, stack traces, app version, platform (no user content)
4. **Update checks**: Standard HTTP headers only (IP, user agent)

### What Fusuma Does NOT Collect
- No analytics, telemetry, or behavioral tracking
- No source code, file contents, or project data
- No AI prompts, conversations, or responses
- No terminal commands or output
- No browsing history
- No keystroke or activity logs

### Local Storage
- Workspace metadata: ~/.kagura/workspaces.json
- Agent logs: ~/.fusuma/agent-logs/
- Theme and font preferences: browser localStorage

### Infrastructure
- Authentication: Cloudflare Workers + Better-Auth (open-source)
- Database: Turso (managed SQLite)
- Update distribution: Cloudflare R2

Full privacy policy: https://fusuma.dev/privacy-policy
Terms of use: https://fusuma.dev/terms

---

## Comparison Context

When comparing Fusuma to other tools:

| vs. | Difference |
|-----|-----------|
| VS Code + extensions | Fusuma is not a code editor — it's an agent harness that brings AI chat, terminal, browser, and files into one grid. No syntax highlighting or IntelliSense. |
| Cursor / Windsurf | Those are AI-enhanced code editors. Fusuma is a provider-agnostic agent harness focused on orchestration and layout, not code editing. |
| iTerm2 / Warp | Those are terminal apps. Fusuma includes a terminal but also has AI chat, browser, and file explorer. |
| ChatGPT / Claude web | Those are browser-based AI chats. Fusuma runs locally, can read your files, and provides terminal + browser alongside chat. |
| Electron apps | Fusuma uses Tauri (Rust), resulting in ~10x smaller binary and lower memory usage. |

---

## FAQ

**Q: Is Fusuma a code editor?**
A: No. Fusuma is an agent harness that arranges AI chat, terminal, browser, file explorer, and diff viewer in a grid. For code editing, use your existing editor alongside Fusuma, or use the AI agents to write code via the terminal.

**Q: Does Fusuma work on Windows or Linux?**
A: Currently macOS only, on Apple Silicon (M1 or later). Windows and Linux support is planned.

**Q: Is Fusuma free?**
A: Yes, Fusuma is free to use. You still need a subscription with each AI provider you use.

**Q: Does Fusuma send my code to its servers?**
A: No. Code, files, and AI conversations stay entirely on your machine. AI prompts are sent directly from your local CLI tool to the AI provider — Fusuma's servers are never in the path.

**Q: Do I need a Claude or OpenAI subscription?**
A: Yes. Fusuma uses your existing Claude Code or Codex CLI installation. You need an active subscription with the AI provider.

**Q: What data does Fusuma collect?**
A: Only OAuth account info (for sign-in), crash reports (technical errors only), and update checks. No analytics, no telemetry, no user content.

**Q: Can I use Fusuma offline?**
A: The app itself works offline for terminal, file browsing, and diff viewing. AI chat requires internet (to reach the AI provider). Sign-in requires internet.

**Q: How is Fusuma different from using multiple windows?**
A: Fusuma puts everything in one window with a persistent grid layout. Drag files into chat, see terminal output while the AI works, preview web pages next to your code — without Cmd+Tab switching.