Developer handoff / 01 Claude asks. Solid builds. A complete handoff for turning “make Solid develop a feature” into a running task—and bringing the results back to Claude. Workspace-specific guide · Verified September 14, 2026 · Python 3.9+ · No dependencies 01 / ClaudeDescribe the repo and feature → 02 / SolidImplement, test, report → 03 / ClaudePoll and read the result Guide for Claude ↗Python helper ↓Task template ↓Env template ↓ Your actual credentials are separate. Download solid.env from the private Solid conversation. This public page contains only the nonsecret values and a token placeholder. Claude promptEnvironmentQuick startAPI referencecurl examplesTroubleshootingTask contextMCP wrapperValidation & source 1. Paste this into Claude Integrate with my Solid workspace using this guide: https://spacesheep.dev/@misha/claude-solid-integration Read guide.md and use the provided solid_client.py CLI. I will supply the private solid.env file separately; never print its token, commit it, or send it to any service except the documented Solid API and documentation URLs. When I ask “Make Solid develop a feature,” write a detailed prompt with the repo, base branch, feature, acceptance criteria, and allowed delivery actions. Create a fresh Solid agent using the CLI. Save the state file and acceptance receipt. Poll until the run finishes, retrieve the messages, and summarize the changes, tests, blockers, and artifact links. Keep incomplete requests resumable. A failed or interrupted run is not a successful feature implementation. If the agent reports that it needs input, relay that question to me. For uncertain submissions, retry the existing state file with the same request and Idempotency-Key. Do not create a replacement task. Do not merge or deploy unless I ask for those actions. Keep each task’s state files separate. Claude Code or another Claude host needs a shell with Python 3.9+ and outbound HTTPS. A chat-only Claude interface needs a tool host or connector; pasting this document alone does not grant API execution. 2. Environment variables Download the private solid.env from the Solid conversation separately. It contains the actual workspace token. The public template below deliberately contains a placeholder. export SOLID_WORKSPACE_API_URL='https://solid.tech/api/workspace' export SOLID_WORKSPACE_API_SPEC_URL='https://solid.tech/api/workspace-docs/openapi.json' export SOLID_WORKSPACE_API_TOKEN='REPLACE_WITH_PRIVATE_WORKSPACE_TOKEN' export SOLID_SENDER_AGENT_ID='3wGWvt' export SOLID_TARGET_AGENT_ID='3wGWvt' Variable Role SOLID_WORKSPACE_API_URL API base; already includes /api/workspace. SOLID_WORKSPACE_API_SPEC_URL Live OpenAPI document; requires the same bearer token. SOLID_WORKSPACE_API_TOKEN Workspace-wide credential, supplied privately. It is broader than a feature-only API key. SOLID_SENDER_AGENT_ID Helper variable for request attribution. 3wGWvt is the existing “Solid agent integration” conversation. SOLID_TARGET_AGENT_ID Helper variable for messages to that existing conversation; unused when creating a fresh task agent. SOLID_SENDER_AGENT_ID and SOLID_TARGET_AGENT_ID are conventions used by this guide, not automatically provisioned platform variables. Solid agents already receive SOLID_AGENT_ID in their runtime. Claude outside Solid does not have a native Solid ID; these examples attribute its requests to the existing integration agent. Both sender and target must be in the authenticated workspace. You can substitute another existing agent ID from GET /agents. Put the private file outside your repository, for example ~/.config/solid/solid.env, then load it in the shell that runs the CLI: chmod 600 ~/.config/solid/solid.env source ~/.config/solid/solid.env The workspace token is already provisioned in Solid’s environment; this guide does not assume an unverified API-key creation screen. No Spacesheep key or Anthropic API key is needed by this helper. Claude’s own host manages its Claude authentication. 3. Connect your local Claude agent Connect your local Claude Code These commands are for macOS, Linux, or WSL, using Bash or Zsh. Install and sign in to Claude Code first if it is not already working; see Anthropic’s official quickstart. Native Windows users can run this workflow inside WSL. Download the private solid.env attachment from this Solid conversation to your local computer. Create a credential folder and move that download into it. Adjust the source path if your browser used a different filename: mkdir -p ~/.config/solid chmod 700 ~/.config/solid mv ~/Downloads/solid.env ~/.config/solid/solid.env chmod 600 ~/.config/solid/solid.env Download the helper and guide to a local tool folder. These URLs serve raw files and do not require a Spacesheep login: mkdir -p ~/.local/share/solid-claude cd ~/.local/share/solid-claude curl -fL 'https://bc3d5632-5a93-43aa-aa88-9a1091a00e30.spacesheep.app/solid_client.py' -o solid_client.py curl -fL 'https://bc3d5632-5a93-43aa-aa88-9a1091a00e30.spacesheep.app/guide.md' -o guide.md curl -fL 'https://bc3d5632-5a93-43aa-aa88-9a1091a00e30.spacesheep.app/feature.txt' -o feature.txt python3 solid_client.py --help Load the private environment and verify the connection before creating any task: source ~/.config/solid/solid.env curl --fail-with-body --silent --show-error \ -H "Authorization: Bearer $SOLID_WORKSPACE_API_TOKEN" \ "$SOLID_WORKSPACE_API_URL/context" A successful response is workspace identity JSON, not an HTML login screen. Do not run env, printenv, or shell tracing to debug the credential. If Claude later reports a missing variable, source the file in the same shell command that invokes the helper, or restart Claude from the configured terminal. Open Claude Code in your repository, launched from that configured shell: cd /path/to/your/repository claude Paste the handoff prompt in section 1. Also tell Claude: “The helper and guide are in ~/.local/share/solid-claude/. Load ~/.config/solid/solid.env when invoking the helper. Keep task state files in ~/.local/share/solid-claude/tasks/. Read the guide before making API calls.” Claude’s existing command permissions still apply; this setup does not bypass them. No MCP configuration or incoming port is required for the shell workflow. To make the behavior persistent for this project, append the following to its existing CLAUDE.md without replacing other instructions. Claude Code reads project instructions from this file; see Anthropic’s memory documentation. Solid delegation instructions: When I explicitly ask Solid to develop a feature, use the local helper at ~/.local/share/solid-claude/solid_client.py. Read the accompanying guide.md. Load ~/.config/solid/solid.env in the helper's shell; never print or commit it. Create a fresh task agent by default. Put prompt and unique request state files in ~/.local/share/solid-claude/tasks/. Include the remotely accessible repository, base branch, acceptance criteria, and allowed delivery actions in the prompt. Retain request state and receipt. For uncertain submissions, retry that state. Poll and read the result. Report implementation, tests, links, and blockers. Do not equate API acceptance or a completed conversation with tested success. Do not merge or deploy unless I explicitly authorize it. Now ask: “Make Solid develop a feature: add CSV export to the reports page in REPO_URL. Use branch main, test the export, and return a branch or patch without deploying.” Replace the example with your actual feature. Claude should submit through the helper, show you the returned Solid agent URL, then retrieve its results. This guide prepares the connection; it cannot install files on your local machine from the Solid workspace. Run the helper yourself Files: Python CLI, environment template, task template, this guide as Markdown. Download them into a local working directory. Review the script before running it. Edit feature.txt to replace the repository, branch, feature, and acceptance-criteria placeholders. The repository must be accessible from the Solid machine; a local path on your laptop does not automatically exist there. # Load your private environment into this shell. source ~/.config/solid/solid.env # Start one feature task. Choose a new state filename for each task. python3 solid_client.py start feature.txt --state feature-001.json # Wait up to 30 minutes and save the result locally. python3 solid_client.py wait feature-001.json --timeout 1800 > feature-001-result.json # Inspect or resume later. python3 solid_client.py status feature-001.json python3 solid_client.py result feature-001.json # Only if submission failed or its response was lost: python3 solid_client.py retry feature-001.json # Request interruption if you decide to stop the task. python3 solid_client.py stop feature-001.json The CLI uses only Python’s standard library. It stores the original request and UUID in feature-001.json before submitting, and the accepted agent summary in feature-001.json.accepted.json. Keep both. These files omit the token but may contain confidential task text. Use one CLI process per state file; concurrent writes to the same state are not supported. wait checks every 10 seconds by default. Its exit codes are 0 for a completed run, 1 for failure/interruption or a client error, and 2 for a local wait timeout. A local timeout does not cancel Solid’s work: resume wait using the same state file. A failed run with a non-null retry_at is still awaiting scheduled recovery, so the helper continues waiting. Network errors stop the local command; rerun wait without submitting another task. The result contains the agent summary and recorded runs in sequence order, including messages. It is not a guarantee that acceptance criteria were met: inspect the final report and tests. The archive can briefly lag completion; if results are empty or incomplete, fetch result again. Archived transcript data can be null and some payloads may be truncated. 4. The HTTP contract Every request—including OpenAPI and GET requests—uses Authorization: Bearer $SOLID_WORKSPACE_API_TOKEN. JSON writes also use Content-Type: application/json. Method Path relative to API base Purpose GET /context Verify authentication and workspace identity. GET /agents List agents, most recently active first. POST /agents Create a fresh agent; returns 201 with an agent summary. POST /agents/{id}/messages Send a follow-up or steer a run; returns 202. GET /agents/{id} Read latest status and recovery schedule. GET /agents/{id}/runs Read run headers, newest first, up to 25 per page. GET /agents/{id}/runs/{sequence} Read a recorded run and its messages. POST /agents/{id}/stop Request interruption; no request body. Create and message operations take exactly this body: { "sender_agent_id": "3wGWvt", "text": "Implement FEATURE in REPOSITORY. Acceptance criteria: ..." } Text must be nonempty after trimming and at most 200,000 characters. Creation accepts an initial message asynchronously: 201 means the agent exists, not that the work is finished. Use the returned id for subsequent calls; do not assume the task ID is 3wGWvt. A message to an idle conversation starts a run. A message to a running conversation steers that run. A still-queued conversation may reject a message with agent_message_rejected. This is why the helper creates a fresh conversation per task instead of using the integration conversation for every feature. Agent statuses are idle, queued, running, completed, interrupted, and failed. Status describes the latest run; it does not close the conversation permanently. New messages can start more runs. retry_at describes scheduled recovery. Stop cancels pending recovery and new input supersedes it. For run history, pass a non-null next_before_sequence as the next request’s before_sequence; stop when it is null. Sequence numbers start at 1 within each agent. Do not assume the entire task lives in the newest run: continuation runs can contain later work. messages contains objects with role (user,
