clide/docs/self-analysis.md

self-analysis.md — can Claude actually work inside clide?

Date: 2026-06-02 Author: Claude (Opus 4.8), run as the dogfood agent against a live clide instance Method: This is not a documentation review. clide was running while I wrote this (socket ~/Library/Caches/clide/05cd448c962214d7.sock, MCP SSE on 127.0.0.1:50354, daemon reports version 2.1.0). I probed my own environment, drove the live daemon, and report what actually happened — with the command transcripts as evidence.

The question on the table: we're close to working together inside clide — what's missing from my end? Here's the honest answer.

---

TL;DR

The daemon is ready. My hands are missing.

Everything the CLI-first contract (D-1, D-6) promises works end-to-end at the socket level — git status, files, editor, pane, exit codes, the lot. I verified it live. But a fresh Claude session dropped into this repo cannot reach any of it, because:

1. There is no clide binary on PATH — and no install path that would put one there.
2. Nothing tells a fresh agent that clide is even running, where its socket is, or that the CLI exists.
3. The live UI surfaces the user sees (the Claude pane, file tree, open files) are not reflected in the registries the CLI reads — pane list and editor list came back empty while clide was open and in use.

The first one is the blocker. The fix is roughly ten lines of Makefile. The other two are the difference between "the agent can issue commands" and "the agent and the user are actually looking at the same workspace."

---

What works today (verified live)

I built the C client (make clide-cli — it had never been built; native/macos-arm64/ did not exist) and pointed it at the running daemon:

$ native/macos-arm64/clide ping
{"pong":true,"ts":"2026-06-02T10:45:31Z","version":"2.1.0"}            # exit 0

$ native/macos-arm64/clide git status
{"branch":"main","upstream":"origin/main","ahead":0,"behind":0,
 "clean":false,"unstaged":[{"path":"governance/README.md",...}, ...]}  # exit 0

$ native/macos-arm64/clide files root
{"path":"/Users/jeroenschweitzer/Projects/clide","ignorePatterns":79} # exit 0

• IPC transport is solid. Unix socket, JSON envelopes, the _argv bridge — all live.

• The command surface is real and broad. pane, files, editor, git, search, pql, panel subsystems all dispatch. git status returned my actual working tree.

• Exit-code discipline is correct (this matters for an agent — it's how I know if a command worked):

  command	exit
  clide ping	0
  clide git status	0
  clide editor open /nonexistent/path	1
  clide status (not a real command)	3

  0/1/3 map cleanly onto the pql contract. Good. An agent can trust these.

So the foundation is genuinely there. The gaps below are about delivery and observability, not the core design.

---

Gap 1 — clide is not on PATH, and nothing installs it there (blocker)

This is the one that stops us cold.

$ which clide          → clide not found
$ clide ping           → command not found (exit 127)

The CLI-first contract assumes I run clide … from Bash. I can't. Digging in:

• The C client (native/clide-cli/clide.c) is the real CLI. It builds only via the separate, non-default target make clide-cli, and the output had never been built.
• make install on macOS copies only the .app bundle to ~/Applications. It never places a clide CLI on PATH.
• make install on Linux symlinks clide → $(INSTALL_PREFIX)/clide/clide, which is the GUI app binary (the Flutter runner), not the C client. So even the Linux path doesn't deliver the shell client.

Net: there is no supported way for the clide command to exist on an agent's PATH. The contract that the entire agent-IDE relationship rests on has no delivery mechanism.

Impact: Total. Without this, "Claude works inside clide via the CLI" is aspirational. I only got there by reverse-engineering the socket path and compiling a C file myself.

Fix (small):

• Make clide-cli a dependency of build/install.
• On macOS install, also drop the built C client somewhere on PATH (~/.local/bin/clide, or /usr/local/bin), and have the GUI launch offer to install it (à la VS Code's "Install 'code' command in PATH").
• Confirm the Linux symlink targets the C client, not the GUI binary.

---

Gap 2 — No bootstrap: a fresh agent doesn't know clide is there

Even with the binary installed, a new session has no signal that it's hosted by clide. There's a discovery file for the MCP path (~/.claude/ide/<pid>.lock, which correctly pointed at workspace + SSE URL), but nothing for the Bash/CLI path:

• No CLIDE_SOCK / CLIDE_WORKSPACE env var in my shell.
• No injected note (CLAUDE.md fragment, system reminder) saying "you're inside clide; use clide … to drive the editor, git panel, and file tree."
• No pre-seeded Bash(clide *) allow rule mentioned anywhere the agent would see it.

I had to be told "you're running inside clide" and then go find the socket. That's not discoverable.

Impact: High. Discovery is the difference between a capability existing and a capability getting used. I won't reach for clide editor open if I don't know it's wired up.

Fix: When clide spawns/hosts an agent, export CLIDE_SOCK/CLIDE_WORKSPACE, ensure clide is on the child's PATH, and inject a short context note describing the CLI surface and the parity contract.

---

Gap 3 — The live UI isn't visible to the CLI (parity premise breaks here)

D-6's promise is two-way: every UI affordance has a CLI verb, and the agent can observe what the user is doing. Right now I can't see the user's surfaces. While clide was open and you were talking to me through it:

$ clide pane list     → {"panes":[]}
$ clide editor active → {"active":null}
$ clide editor list   → {"buffers":[]}

Empty. Either the built-in UI panes (the Claude conversation pane, the file tree, any open viewer) don't register into the daemon registries the CLI reads, or those registries only track CLI-spawned entities. Either way, the consequence is the same: I cannot tell what file you're looking at, what's selected, or what panes are open. The "agent sees what the user sees" half of parity isn't there yet.

Impact: High for real collaboration. Half of working together is me reacting to what's on your screen ("you've got dispatcher.dart open — want me to jump to the handler that's failing?"). Today I'm blind to it.

Fix: Make the built-in extensions register their panes/buffers/active-file state through the same registries the pane/editor CLI reads. Add a clide status umbrella (see Gap 6) that returns a one-shot snapshot: active pane, focused file + selection, git summary, layout.

---

Gap 4 — Event observation doesn't fit how an agent runs

clide tail --events is the design's answer to "how does Claude see state change." But a streaming, never-returning command is awkward from a request/response tool loop — I can't sit on an open stream the way a long-lived UI client can. I either background it and poll a file, or I miss events.

This is more ergonomic than broken, and it overlaps the still-open Q-2 (back-pressure) and Q-3 (event persistence/audit). But for me specifically it matters.

Impact: Medium. Without a pull-based form I'll just re-run git status / editor active on demand and never use the event bus — which means I miss things that happen between my polls.

Fix: Offer a cursor-based pull alongside the stream: clide events --since <cursor> returning everything since the cursor plus a new cursor. That fits an agent loop natively and dovetails with Q-3's persistence question.

---

Gap 5 — Which Claude is the dogfood agent? (needs a decision)

There's an unresolved ambiguity I bumped straight into. My shell reports TERM_PROGRAM=zed — i.e. this Claude (me) is an external Claude Code harness, not a session clide spawned via the stream-json protocol (D-77/D-78). So there are two distinct "Claude inside clide" stories, and they have different gaps:

• (A) clide-hosted session — clide spawns claude --output-format stream-json, renders the conversation natively, handles permission prompts as native cards (D-77/D-78). This is the user's primary Claude pane.
• (B) external agent driving via CLI — a Claude Code process (like me) that issues clide … commands to manipulate the IDE.

These aren't the same agent. In (A), the hosted Claude is the conversation but would itself need clide on PATH to drive the surrounding IDE (Gaps 1–3 apply to it too). In (B), clide can observe my clide … IPC calls but is blind to the rest of my tool use (file reads, make test, plain git) because my shell isn't clide-owned.

Impact: Medium, but foundational — it decides what "working together inside clide" even means. Worth a short governance note (Q- or D-record) pinning down the intended model: is the dogfood agent the hosted stream-json session, an external CLI driver, or both?

---

Gap 6 — Minor / cleanup

• No clide status command. There's no single one-shot "what's the whole state right now" call — the natural first thing an agent reaches for. (status currently returns exit 3, unknown command.) Cheap to add and high-value for orienting.
• MCP transport is up but not reachable by me. The SSE server is live (:50354), but mcp__ide__* tools aren't in my tool list this session, and getDiagnostics/executeCode were noted as stubs. So neither transport (CLI nor MCP) is actually wired to an external agent out of the box. The CLI path is the one to fix first (Gap 1); MCP can follow.
• Version drift cosmetic check: daemon reports 2.1.0; worth confirming that matches pubspec.yaml so an agent keying off clide version isn't misled.

---

Minimum to actually dogfool (priority order)

1. Ship clide on PATH. Build the C client by default; install it to a PATH dir on macOS and Linux (targeting the C client, not the GUI binary). (Gap 1 — blocker)
2. Bootstrap the agent. Export CLIDE_SOCK/CLIDE_WORKSPACE, ensure PATH, inject a context note + Bash(clide *) allow rule when clide hosts/launches an agent. (Gap 2)
3. Make the live UI observable. Register built-in panes/buffers into the CLI-visible registries; add clide status for a one-shot snapshot. (Gaps 3, 6)
4. Add pull-based events (clide events --since). (Gap 4)
5. Decide the agent model in governance — hosted session vs external CLI driver vs both. (Gap 5)

Items 1–2 are small and unblock everything. With just those, I can drive the IDE from Bash today — I proved the daemon answers. Item 3 is what turns "I can issue commands" into "we're actually working in the same workspace."

---

Everything above was checked against a running clide, not inferred from docs. The pleasant surprise is how little is actually broken: the hard part (a live, correct, single-process IPC contract with proper exit codes) is done and working. What's missing is the last mile that puts the tool in the agent's hands and lets the agent see the room.