clide/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What clide is

A Flutter desktop IDE for Claude Code. Three surfaces, one coherent tool:

• app/ — Flutter desktop application (Linux / macOS primary; Windows stretch).
• sidecar/ — Go sidecar/CLI, single binary with two modes: clide <subcommand> (one-shot for Claude) and clide --daemon (long-running for the app). Owns PTYs, subprocesses, file watchers, git, pql invocations.
• pql — external supporter tool. Clide wraps it for every query surface; never re-implements it.

App ↔ sidecar ↔ CLI speak a single JSON-lines unix socket protocol. The sidecar outlives app restarts so Claude sessions survive reopens.

Design doc: docs/initial-plan.md. Decisions: docs/ADRs/. Python Textual predecessor under legacy/.

Guardrails

These are load-bearing. Violating any means the design is wrong, not the rule.

• Flutter desktop is the host. No Electron, ever. Web target may work as a happy accident — don't compromise desktop fidelity for it. xterm.dart is the terminal renderer.
• No heavy lifting in the UI layer. Flutter app renders and handles input. PTYs/subprocesses/filesystem/git all live in the sidecar.
• CLI-first, not MCP. Claude talks via Bash (clide ...), matching pql's contract. See ADR 0001.
• Sidecar language: Go. Module git.schweitz.net/jpmschweitzer/clide/sidecar. See ADR 0002.
• User/Claude parity. Every CLI subcommand has a UI affordance in the app, and every UI action has a CLI. If you add one side without the other, the feature is incomplete.
• pql: wrap, don't duplicate, and treat it as a clide subsystem when present. Pql logic only lives in sidecar/internal/pql/ (pure shell-outs). Clide owns pql's ignore_files: config key; it never touches pql's .pql/ index/cache data. See ADR 0003.
• Repo-is-the-workspace. The git repo root is the workspace — no parallel "vault" concept. Clide dogfoods against its own repo.
• Ignore discipline. Single knob: ignore_files: in .pql/config.yaml, ordered layering. Default [.gitignore]; clide writes [.gitignore, .clideignore] when .clideignore exists. See ADR 0004.

Tier ordering (don't skip ahead)

1. Tier 0 — Flutter app + sidecar daemon handshake, empty IDE shell.
2. Tier 1 — Claude in an xterm.dart pane; session persists across app restarts.
3. Tier 2 — Pane model + active-file awareness + clide open/active/insert/replace-selection/tail.
4. Tier 3 — Git panel (staged/unstaged, hunk stage, conflict UI) + diff tab + clide git ….
5. Tier 4 — pql integration: Query panel, file tree, backlinks, problems — all drawing from pql.
6. Tier 5 — Canvas (CustomPaint + InteractiveViewer) and graph view.
7. Tier 6 — Dart extension API, settings, theming, distributable builds.

See docs/initial-plan.md for the full tier definitions and acceptance criteria.

Parent projects

• legacy/ — Python Textual clide v1.2.0. Feature-frozen. Reference for the pane model, panel set, git skills (/commit, /stash, /pull, /push — rewire to clide git …), TODO.md parsing format.
• projects/claudian (April 2026, discarded) — 2-day experiment with an Obsidian-plugin approach. Its architectural patterns (Go sidecar, CLI-first, pql-as-subsystem, ignore-file strategy, supply-chain gate, changelog discipline, commit conventions) are the ADRs and skills you see here.
• projects/pql — active supporter tool. Clide depends on it; never duplicates it.

Dependencies & supply chain

• Go (sidecar): exact-pin versions (never @latest). make vuln (govulncheck ./...) runs after every dep add/bump and gates CI.
• Dart (app): prefer-zero-deps. Flutter-SDK widgets first; third-party packages need justification. What stays is exact-pinned in pubspec.yaml (no caret ranges). Advisories reviewed before every bump; pubspec.lock committed.
• go.sum and pubspec.lock are always committed.
• make security aggregates the Go and Dart CVE gates; ci/security.sh is the CI entry.

Commands

(Placeholder until Phase 3 commits land these targets.)

make build           # build sidecar/bin/clide
make test            # go test ./...
make test-race       # with race detector
make lint            # golangci-lint
make vuln            # govulncheck (sidecar CVE gate)
make app-build       # flutter build linux / macos
make app-test        # flutter test
make app-analyze     # dart analyze
make security        # run all CVE gates (go + dart)
make push-check      # full pre-push gate: lint + test + test-race + vuln + app-analyze + app-test
make hooks           # install the repo's git hooks (one-time setup)
make tools           # install Go tooling at pinned versions (govulncheck, goimports, golangci-lint)
make clean           # remove build artefacts

One-time setup on a fresh clone: make tools && make hooks, plus cd app && flutter pub get once Flutter is installed.

Changelog discipline

Keep a Changelog 1.1.0. Every user-visible commit adds an entry under ## [Unreleased] in CHANGELOG.md. Cutting a release means moving Unreleased entries under a new dated version heading and bumping project.yaml version: in the same commit — see .claude/skills/git-commit/SKILL.md for the full rule.

Open questions

• .canvas schema compatibility with Obsidian — decide during Tier 5 spike.
• Extension API shape (widgets, subcommands, both) — decide during Tier 6.
• IPC wire-format stability + schema_version: in project.yaml — decide when the first real subcommand lands.
• Editor tab: full LSP integration via sidecar vs tree-sitter-only highlight — decide during Tier 2.