Claude Code Harness
Claude Code harness deep dive: setup, provider auth, launch arguments, project-root behavior, and troubleshooting.
1 min read
Claude Code is Anthropic's coding-agent CLI. Coven launches it as a project-rooted PTY and records the run as a Coven session.
| Field | Value |
|---|---|
| Harness id | claude |
| Executable | claude |
| Install | npm install -g @anthropic-ai/claude-code |
| Provider auth | claude doctor |
| First run | coven run claude "polish this UI" |
Setup
npm install -g @anthropic-ai/claude-code
claude doctor
coven doctorcoven doctor checks that claude is available on PATH. It does not read Anthropic credentials.
Launch
coven run claude "refactor this component" --cwd packages/web --title "Web refactor"In interactive terminals, Coven launches Claude Code with the prompt as the final argument. In non-interactive mode, Coven uses Claude Code's --print shape so output can be captured by callers.
Supervision flow
Common failures
| Symptom | Likely cause | Fix |
|---|---|---|
coven doctor reports Claude Code missing | claude is not on daemon PATH | Install Claude Code, restart daemon, rerun doctor. |
| Claude prompts for setup | Provider auth is incomplete | Run claude doctor. |
| Launch rejects cwd | --cwd escapes the project root | Use a cwd inside the project. |
For shared setup rules, see Install harness CLIs and Provider auth boundary.
Owner-scoped writes
The separate --write-scope source-build profile requires a qualified macOS Claude streamed launch, with no fallback to unrestricted Full. It confines shell and file-tool writes while leaving explicit limits around reads, networking, MCP servers and external actors. It does not load user/project native settings as extra permission sources. See Claude scoped writes for the document, qualification checks and limits; provider login and ordinary interactive sessions keep their existing behavior.
Last updated on