crow-cli 0.1.46__tar.gz → 0.1.47__tar.gz

crow_cli-0.1.47/.gitignore

@@ -0,0 +1,54 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# keys
+.env
+
+# test database
+*.db
+*.db*
+
+# test caches
+.pytest_cache
+config/logs/*.log
+config-done
+
+# MyST build output
+docs/_build/
+_site/
+
+crow-editor/frontend/node_modules
+
+*.log
+*.log*
+
+sandbox/lancedb-testing/pylate_lancedb/
+
+# Rust
+target/
+
+# web workspace (bun): node_modules everywhere; the vendored aui dists ARE
+# the source of truth for packages/aui, so they stay tracked
+node_modules/
+!packages/aui/*/dist/
+!packages/aui/*/dist/**
+
+# playwright-cli scratch state
+.playwright-cli/
+
+# vendored VSCodium build pipeline (packages/crow-gui): its build/ directory is
+# packaging SOURCE (linux/osx/windows/alpine package scripts), not an artifact,
+# so the generic build/ rule above must not swallow it.
+!packages/crow-gui/vscodium/build/
+# ...but gulp's scratch dir inside the vendored tree (sysroot caches) is an artifact.
+packages/crow-gui/vscodium/.build/
+# vsix download cache for the bundled extensions (bundle-exts.sh).
+packages/crow-gui/.build/

crow_cli-0.1.47/AGENTS.md

@@ -0,0 +1,68 @@
+# RULES
+
+## Launching crow: one agent server, in its own terminal
+
+The agent is a **server**; the clients are separate processes. Never write the
+launch as one chained command (`crow-cli acp2 --http && crow`, or `&`-backgrounding
+the agent in the same block as the client). That reads as "this one command starts
+both", and it does not — the IDE and the browser client spawn nothing at all.
+
+In one terminal, run a **single instance** and leave it running:
+
+```bash
+crow-cli acp2 --http        # ACP v2 over Streamable HTTP + WebSocket → ws://127.0.0.1:2771/acp
+```
+
+In another terminal, run a client:
+
+```bash
+crow                                                   # the IDE
+cargo run -p crow-web -- --port 2770 \
+    --acp-url ws://127.0.0.1:2771/acp                  # the browser client
+```
+
+One instance serves every dialling client on the machine. Do not start one per
+client, and do not restart it to change a client.
+
+## The args, and where they live
+
+| Arg / setting | Where | Default | Meaning |
+|---------------|-------|---------|---------|
+| `--http` | `crow-cli acp`, `crow-cli acp2` | off (stdio) | serve Streamable HTTP + WebSocket instead of stdio |
+| `--host` | same | `127.0.0.1` | bind address; `0.0.0.0` exposes it beyond loopback |
+| `--port` | same | `2769` (v1), `2771` (v2) | the two protocol versions have two ports |
+| `-d/--config-dir`, `-o/--config-file`, `-m/--model`, `-p/--system-prompt-path`, `--debug` | same | — | per-instance config overrides |
+| `crowAcp.endpoint` | IDE extension settings | `ws://127.0.0.1:2771/acp` | what the chat panel dials |
+| `crowAcp.protocol` | IDE extension settings | `2` | `1`, `2` or `auto` (detect) |
+| `crowAcp.cwd` | IDE extension settings | the workspace folder | agent working directory |
+| `crowAcp.mcpConfig` | IDE extension settings | `crow-cli mcp2` (YAML) | the tool supply handed over at `session/new` |
+| endpoint field | browser SPA header (`packages/chat`) | `ws://127.0.0.1:2771/acp` | persisted in `localStorage` |
+| `--acp-url` | `crow-web` | `ws://127.0.0.1:2769/acp` | upstream of its `/acp` proxy — the **v1** port; pass it explicitly to join a v2 server |
+| `--port`, `--root`, `--shell` | `crow-web` | `2770`, cwd, `$SHELL` | listener, owned workspace, pty shell |
+| `--agent`, `--agent-arg` | `crow-agent` | `crow-cli acp2` or `$CROW_AGENT` | the stdio agent it spawns itself |
+| `-w/--workspace`, `--session-id`, `--model`, `--theme` | `crow-agent` | cwd, —, `$CROW_MODEL`, persisted | client-side session choices |
+| `mcpServers` | `~/.agents/crow/config.yaml` | written by `crow-cli init` | the supply `crow-cli run` passes at `session/new` |
+| `agent_servers` | `~/.agents/crow/config.yaml` | one `crow-cli` entry from init | what `run` spawns; the top entry is the default |
+
+## Which client starts the agent
+
+- **Spawns its own over stdio:** `crow-cli run` (top `agent_servers` entry), `crow-agent` (`--agent`).
+- **Dials a running server:** the IDE chat panel, the browser SPA, and `crow-web`'s `/acp` proxy.
+- **Third-party clients** (Zed, …) spawn the command you declare, and forward their
+  `context_servers` as the tool supply.
+
+## Two rules that are easy to get wrong
+
+**The agent has no builtin tools.** Whatever MCP servers the client passes at
+`session/new` are exactly the tools that session gets; empty means zero tools.
+`crow-cli init` writes a global `mcpServers.crow-mcp` entry, and an
+`agent_servers` entry may carry its own `mcpServers` that replaces the global
+supply for that agent only.
+
+**Nothing runs from a source checkout implicitly.** `cli/source.py:spawn_argv()`
+is always the code that is actually running — a frozen build's own subcommand, or
+`sys.executable -m crow_cli.agent[2].main`. `crow-cli init` clones
+`~/.agents/crow/src/crow-cli` and writes one explicit `agent_servers` entry
+pointing at it; that entry is ordinary config the user can edit or delete
+(`--no-source` writes neither). Do not reintroduce an implicit checkout
+override: it fights worktrees and project checkouts.