Local AI Agent asset visualization and management tool
Features · Quick Start · Screenshots · Development · Architecture · AI Workflow · User Manual
As AI coding agents like Claude Code, Codex, and Cursor evolve, users accumulate dozens of local assets — skills, MCP servers, hooks, plugins, commands, memories, sessions — spread across multiple directories as plain text files. These assets are installed and forgotten, with no unified way to see what you have, how they relate, or how much you're spending.
Berth makes these invisible assets visible. It scans your local machine, discovers all your AI agent configurations, and presents them in a clean, Finder-inspired desktop interface.
v0.1 focuses on Claude Code with read-only asset visualization. No files are modified. No data leaves your machine.
- Asset Discovery — Automatically scans 25+ asset types from
~/.claude/and project directories - Five Module Views — Overview dashboard, Sessions, Instructions, Capabilities, Usage
- Scope Merge Display — See how user, project, and enterprise configurations merge together
- Session Browser — Browse all Claude Code sessions with metadata, loaded skills, MCP servers, and costs
- Import Chain Resolution — Visualize
@pathimport chains in CLAUDE.md / AGENTS.md files - Usage Analytics — Track spending, token usage, and rate limits with charts
- Global Search — Search across all assets by name, type, or scope (⌘K / Ctrl+K)
- File Watching — Real-time updates when asset files change on disk
- Dark Mode — Full dark/light/system theme support
- i18n — English and Chinese interface
- Cross-Platform — macOS and Windows
Download the latest release for your platform from the Releases page.
# Clone the repository
git clone https://github.com/Caldis/berth.git
cd berth
# Enable corepack so the pinned pnpm 9.x is used
# (corepack's default is pnpm 11, which skips native build scripts and breaks the build)
corepack enable
# Install dependencies (compiles better-sqlite3, downloads Electron)
pnpm install
# Start development server
pnpm dev
# Build for production
pnpm package- Node.js 20+
- pnpm 9.x — auto-pinned via
corepack enable(the repo declarespackageManager: pnpm@9.15.4; do not use pnpm 10/11) - Claude Code installed (Berth scans
~/.claude/)
Screenshots coming soon
┌─────────────────────────────────────────┐
│ Renderer (React + TypeScript) │
│ • shadcn/ui + Tailwind CSS │
│ • Zustand state management │
│ • react-router-dom navigation │
│ • recharts for data visualization │
│ • i18next for internationalization │
└──────────┬──────────────────────────────┘
│ IPC (contextIsolation)
┌──────────┴──────────────────────────────┐
│ Main Process (Electron + Node.js) │
│ ┌─────────────────────────────────┐ │
│ │ Claude Code Adapter │ │
│ │ • 25+ asset type scanners │ │
│ │ • YAML/JSON/Markdown parsers │ │
│ │ • @path import resolver │ │
│ └─────────┬───────────────────────┘ │
│ ┌─────────┴───────────────────────┐ │
│ │ Asset Engine │ │
│ │ • Full scan + incremental │ │
│ │ • chokidar file watching │ │
│ │ • MiniSearch full-text index │ │
│ │ • Relation resolver │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────────┘
│ read-only fs access
┌─────────────────────────────────────────┐
│ ~/.claude/ + project .claude/ dirs │
└─────────────────────────────────────────┘
This repo ships an AI Native Workflow harness — a repo-contained workflow for developing Berth with AI coding agents (Claude Code and Codex), so a task can be picked up across sessions and across people without losing context.
| Path | Purpose |
|---|---|
.agents/workflow/*.md |
Single source of truth — the workflow playbooks (hand-written) |
.agents/README.md |
Harness overview and how distribution works |
.agents/skills/, .claude/skills/ |
Generated skill entry points for Codex and Claude Code |
docs/ARCHITECTURE.md |
Project Map — process/module boundaries, IPC contract |
docs/works/ · docs/friction/ · docs/issues/ |
Per-task state · captured engineering friction · product issues |
scripts/harness-sync.mjs · scripts/harness-check.mjs |
Regenerate distribution · validate it |
The workflow is Explore → Design → Implementation → Verify, with optional Polish before archive. Invoke the matching skill from the repo root (/harness-new in Claude Code, $harness-new in Codex):
harness-new <task description> # scaffold a task under docs/works/
harness-explore # gather context → 01-ANALYSIS.md
harness-design # tech design (asks you to clarify) → 02-SPEC.md + 03-PLAN.md
harness-implement # build per the plan, with tests
harness-verify # full tests + review + UI acceptance
harness-polish # optional, only when explicitly requested or approved
harness-archive # sync GitHub Project to Done, archive the task, commit
Humans steer at design (clarify intent) and verify (confirm acceptance); the agent runs the rest. Full command list and contract: see .agents/README.md.
pnpm harness:sync # regenerate command/skill distribution after editing .agents/workflow/*
pnpm harness:check # validate task structure, naming, and distribution (also runs in CI)After cloning, the distribution (symlinks + stubs) is already committed and works as-is — harness:sync is only needed when you change the playbooks.
| Component | Technology |
|---|---|
| Framework | Electron 33 (electron-vite 5) |
| Frontend | React 19 + TypeScript 5.9 |
| UI | shadcn/ui + Tailwind CSS 3.4 |
| State | Zustand 5 |
| Router | react-router-dom 7 |
| Charts | Recharts 2 |
| i18n | i18next + react-i18next |
| Search | MiniSearch |
| Storage | better-sqlite3 |
| File Watch | chokidar |
| Unit Tests | Vitest |
| E2E Tests | Playwright |
src/
├── main/ # Electron main process
│ ├── adapters/ # Agent adapters (Claude Code)
│ ├── engine/ # Asset scanning, watching, search
│ └── ipc/ # IPC handler registration
├── preload/ # Context-isolated preload scripts
├── renderer/ # React application
│ └── src/
│ ├── components/ # UI components (layout, shared, ui)
│ ├── pages/ # Route page components
│ ├── stores/ # Zustand state stores
│ ├── hooks/ # Custom React hooks
│ ├── i18n/ # Translations (en, zh)
│ ├── lib/ # Utilities
│ └── styles/ # Global CSS + Tailwind
└── shared/ # Shared types between processes
└── types/ # Asset model, IPC contracts
pnpm dev # Start dev server with HMR
pnpm build # Build for production
pnpm package # Build + package installer
pnpm package:mac # Package for macOS
pnpm package:win # Package for Windows
pnpm test # Run unit tests
pnpm test:watch # Run tests in watch mode
pnpm test:e2e # Run E2E tests
pnpm typecheck # TypeScript type checking
pnpm lint # ESLintpnpm dev runs electron-vite with --watch, so renderer, main, and preload changes can refresh through the user's own dev process. If a dev process was already running before this script changed, restart it once so the running process picks up --watch.
Berth is designed with security as a first principle:
- Read-only — v0.1 never writes to any local files
- Credential isolation — OAuth tokens and API keys are never loaded into the renderer process. Only file existence is detected, marked as
sensitive: true - Context isolation — Electron best practices:
contextIsolation: true,nodeIntegration: false - No telemetry — Zero data leaves your machine. Fully local.
- Path whitelist — Scanner only accesses predefined paths
- Only Claude Code is supported in v0.1 (Codex/Cursor adapters planned for v0.3)
- Session content is not displayed (only metadata)
- Assets are read-only — editing comes in v0.2
- MCP server start/stop is not supported (v0.3)
| Version | Focus |
|---|---|
| v0.1 | Claude Code read-only asset visualization (current) |
| v0.2 | Asset editing + import chain visualization + cross-session search |
| v0.3 | Codex / Cursor adapters + unified cross-agent view |
| v0.4 | Team baseline export + config sync suggestions + MCP management |
| v0.5+ | Command palette / automation suggestions / mobile companion |
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
Built with ⚓ by Caldis