{"id":48705661,"url":"https://github.com/jeremyguo/clawparty","last_synced_at":"2026-04-24T08:01:37.757Z","repository":{"id":350615392,"uuid":"1195948970","full_name":"JeremyGuo/ClawParty","owner":"JeremyGuo","description":"🦀 A self-hosted, multi-agent service framework built in Rust. Agents as services, not scripts.","archived":false,"fork":false,"pushed_at":"2026-04-18T20:26:39.000Z","size":5966,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-18T22:14:50.496Z","etag":null,"topics":["agent","llm","multi-agent","rust","self-hosted","telegram"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JeremyGuo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-30T08:14:12.000Z","updated_at":"2026-04-18T20:26:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/JeremyGuo/ClawParty","commit_stats":null,"previous_names":["jeremyguo/clawparty"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/JeremyGuo/ClawParty","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeremyGuo%2FClawParty","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeremyGuo%2FClawParty/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeremyGuo%2FClawParty/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeremyGuo%2FClawParty/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JeremyGuo","download_url":"https://codeload.github.com/JeremyGuo/ClawParty/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeremyGuo%2FClawParty/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32214420,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T03:15:14.334Z","status":"ssl_error","status_checked_at":"2026-04-24T03:15:11.608Z","response_time":64,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","llm","multi-agent","rust","self-hosted","telegram"],"created_at":"2026-04-11T11:05:01.834Z","updated_at":"2026-04-24T08:01:37.750Z","avatar_url":"https://github.com/JeremyGuo.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Stellaclaw\n\n**A Rust-native agent server for long-running, multi-channel AI conversations.**\n\nAgents as durable services, not disposable prompts.\n\n[Roadmap](ROAD_MAP.md) · [Version History](VERSION) · [Example Config](example_config.json)\n\n\u003c/div\u003e\n\n---\n\n## What Is Stellaclaw?\n\nStellaclaw is the next-generation runtime for ClawParty: a self-hosted agent server that runs continuously, receives messages from external channels, and drives LLM sessions with durable state, tools, skills, workspaces, and crash recovery.\n\nThe current implementation is intentionally split into two runtime layers:\n\n| Layer | Binary / Crate | Owns |\n|---|---|---|\n| Host | `stellaclaw` | Channels, conversations, workdirs, Telegram UI, config, routing, delivery, runtime skill persistence. |\n| Session execution | `agent_server` + `stellaclaw_core` | SessionActor state machine, provider calls, tool batches, compaction, session history, runtime metadata. |\n\nIn one line:\n\n```text\nConversation = durable boundary + router\nSessionActor = execution boundary + state machine\n```\n\nThis shape keeps platform concerns out of the model loop and keeps session execution recoverable, testable, and easy to isolate.\n\n---\n\n## Current Status\n\nStellaclaw is already usable as a Telegram-backed agent host.\n\nImplemented today:\n\n- Telegram channel with inbound messages, attachments, typing indicator, progress panel, and final success/failure delivery.\n- Per-conversation model switching, sandbox switching, remote workspace switching, status query, cancel, and continue.\n- `agent_server` subprocess boundary using stdin/stdout line-delimited JSON-RPC.\n- SessionActor control/data mailboxes, turn loop, tool batch executor, idle compaction, crash recovery, and unfinished-turn continuation.\n- Codex subscription provider using the official websocket shape, including access token refresh and priority service tier support.\n- OpenRouter chat-completions / responses providers, Claude provider, Brave Search provider, and provider-backed media helpers.\n- Model-aware multimodal input normalization with graceful downgrade to text context when a model cannot accept a file modality.\n- Built-in tools for files, search, patching, shell, downloads, web fetch/search, media, cron, subagents, and host coordination.\n- Runtime `SKILL.md` system with `skill_load`, `skill_create`, `skill_update`, and `skill_delete`.\n- Workdir migration from legacy PartyClaw layouts into the current Stellaclaw layout.\n\nPlanned next surfaces:\n\n- Web channel.\n- RESTful API for external systems and admin UI.\n- Richer host management and observability.\n\nSee [ROAD_MAP.md](ROAD_MAP.md) for the full architecture direction.\n\n---\n\n## Architecture\n\n```mermaid\nflowchart LR\n    User[User or external platform]\n\n    subgraph Host[Host process: stellaclaw]\n        Ingress[Channel ingress]\n        Conv[Conversation thread]\n        Delivery[Outgoing delivery]\n        CStore[(Conversation state)]\n        WStore[(Workspace and runtime bindings)]\n    end\n\n    IPC{stdio JSON-RPC}\n\n    subgraph Runtime[Session process: agent_server]\n        Rpc[Session RPC thread]\n        Actor[SessionActor]\n        Tools[ToolBatchExecutor]\n        SStore[(Session state)]\n    end\n\n    User --\u003e Ingress\n    Ingress --\u003e Conv\n    Conv --\u003e CStore\n    Conv --\u003e WStore\n    Conv --\u003e IPC\n    IPC --\u003e Rpc\n    Rpc --\u003e Actor\n    Actor --\u003e Tools\n    Tools --\u003e Actor\n    Actor --\u003e SStore\n    Actor --\u003e Rpc\n    Rpc --\u003e IPC\n    IPC --\u003e Conv\n    Conv --\u003e Delivery\n    Delivery --\u003e User\n```\n\n### Why This Split?\n\n- Channel code stays platform-specific and user-facing.\n- Conversation code owns durable routing decisions and workspace materialization.\n- SessionActor owns the model/tool loop and session history.\n- Provider requests and tools can evolve without turning Telegram or future Web code into session internals.\n- A crashed or restarted service can resume from persisted conversation/session state.\n\n---\n\n## Telegram Experience\n\nThe Telegram channel is the primary product surface right now.\n\nSupported controls:\n\n| Command | Purpose |\n|---|---|\n| `/model` | Change the conversation model. |\n| `/remote` | Select or clear remote workspace execution mode. |\n| `/sandbox` | Override sandbox mode for this conversation. |\n| `/status` | Show current conversation/session status. |\n| `/continue` | Continue a recoverable failed or unfinished turn. |\n| `/cancel` | Cancel the active turn where possible. |\n\nDuring a turn, Telegram receives:\n\n- typing status while the agent is working;\n- editable progress feedback;\n- final assistant output;\n- recoverable failure prompts when `/continue` is available.\n\nEach conversation has its own workspace, model snapshot, sandbox override, remote binding, and foreground/background session bindings.\n\n---\n\n## Tooling\n\nStellaclaw exposes tools through a dynamic catalog that is rebuilt from runtime state, model capabilities, session type, and remote mode.\n\n| Family | Examples |\n|---|---|\n| Files and search | `file_read`, `file_write`, `edit`, `apply_patch`, `grep`, `glob`, `ls` |\n| Shell | `shell`, `shell_close` |\n| Web | `web_fetch`, `web_search` |\n| Downloads | `file_download_start`, `file_download_progress`, `file_download_wait`, `file_download_cancel` |\n| Media | `image_load`, `pdf_load`, `audio_load`, provider-backed analysis/generation tools |\n| Host coordination | subagents, background sessions, cron, status and conversation bridge tools |\n| Skills | `skill_load`, `skill_create`, `skill_update`, `skill_set_upstream`, `skill_delete` |\n\nRemote mode is schema-aware:\n\n- selectable mode exposes a `remote` field where tools can choose a local or SSH target;\n- fixed remote mode hides `remote` entirely and treats the bound execution root as implicit.\n\nThe shell tool intentionally uses `command` for new commands. It does not accept a `cmd` alias.\n\n---\n\n## Skills\n\nSkills are `SKILL.md` directories synced into each workspace:\n\n```text\n.skill/\n  web-report-deploy/\n    SKILL.md\n    references/\n    scripts/\n    assets/\n```\n\nThe runtime tracks skill metadata and loaded skill content. When a skill changes, the session receives a runtime skill update before the next real user message.\n\nPersistent skill operations are host bridge tools:\n\n- `skill_create` persists a staged workspace skill into `rundir/.skill/\u003cname\u003e`.\n- `skill_update` validates and updates an existing runtime skill.\n- `skill_set_upstream` configures a git repo for a shared runtime skill. Future `skill_update` calls commit and push that runtime skill to the configured repo and branch.\n- `skill_delete` removes it from the runtime store and existing conversation workspaces.\n\n`SKILL.md` frontmatter should include at least:\n\n```yaml\n---\nname: web-report-deploy\ndescription: Generate and deploy static web reports.\n---\n```\n\n---\n\n## Multimodal Input\n\nFiles and media are normalized at the session boundary, just before provider requests are built.\n\nIf the selected model supports the modality, Stellaclaw sends it using the configured model transport. If it does not, the file becomes plain text context containing the file path, name, media type, and downgrade reason.\n\nThat means a conversation can keep working even when a model lacks `image_in`, `pdf`, `audio_in`, or generic file input support.\n\nEach local conversation workspace has a `shared/` directory linked to `rundir/shared`, so files placed there are visible from other conversation workspaces in the same workdir. `sandbox.software_dir` can also expose a shared software/tooling directory; in bubblewrap mode it is mounted at `sandbox.software_mount_path` (default `/opt`) and tools receive `STELLACLAW_SOFTWARE_DIR`.\n\n---\n\n## Providers\n\nCurrent provider support includes:\n\n- Codex subscription websocket with automatic access token refresh.\n- OpenRouter chat completions.\n- OpenRouter responses.\n- OpenAI-compatible image generation and edits.\n- Claude messages.\n- Brave Search.\n\nModel behavior is configured with `ModelConfig`, including capabilities, multimodal input transport, context window, timeout, retry mode, token estimation, cache TTL, and optional fast/priority service tier.\n\nFor `openai_image`, configure `url` as the API base such as `https://host/v1`; Stellaclaw routes generation requests to `/images/generations` and image edit requests to `/images/edits`.\n\n---\n\n## Quick Start\n\n### 1. Build\n\n```bash\ncargo build --workspace --release\n```\n\nThis produces:\n\n```text\ntarget/release/stellaclaw\ntarget/release/agent_server\n```\n\n### 2. Configure\n\nStart from [example_config.json](example_config.json).\n\nImportant fields:\n\n- `version`: current config schema version, currently `0.4`.\n- `agent_server.path`: path to the `agent_server` binary.\n- `models`: named model configs.\n- `channels`: Telegram and future channel definitions.\n- `sandbox`: default sandbox mode.\n\nFor a release build, set:\n\n```json\n{\n  \"agent_server\": {\n    \"path\": \"target/release/agent_server\"\n  }\n}\n```\n\nSet the environment variables referenced by your config, for example:\n\n```bash\nexport TELEGRAM_BOT_TOKEN=...\nexport OPENROUTER_API_KEY=...\nexport BRAVE_SEARCH_API_KEY=...\n```\n\n### 3. Run\n\n```bash\ntarget/release/stellaclaw \\\n  --config example_config.json \\\n  --workdir ./stellaclaw_workdir\n```\n\nThe workdir stores conversations, sessions, runtime skills, logs, and migration markers.\n\n### 4. systemd\n\nThe local deployment used by this repository runs as a user service:\n\n```bash\nsystemctl --user restart stellaclaw\nsystemctl --user status stellaclaw --no-pager\n```\n\nYour unit should point `ExecStart` at `target/release/stellaclaw` and pass `--config` plus `--workdir`.\n\n---\n\n## Version Files\n\nStellaclaw deliberately has separate version tracks:\n\n| File / Field | Meaning |\n|---|---|\n| Root `VERSION` | Project release version and changelog. Starts at `1.0.0`. |\n| Config JSON `version` | Config schema version. Currently `0.4`. |\n| Workdir `STELLA_VERSION` | Workdir schema version. Currently `0.5`. |\n| Legacy workdir `VERSION` | PartyClaw compatibility input, not the project release version. |\n\nBefore bumping the root `VERSION`, check whether the previous GitHub Release exists. If it does not, merge the unpublished changelog into the next release notes so release history does not skip user-visible changes.\n\n---\n\n## CI/CD\n\nGitHub Actions currently provides:\n\n| Workflow | Trigger | What it does |\n|---|---|---|\n| CI | push to `main`, pull request | `cargo fmt --all --check`, `cargo test --workspace --locked` |\n| Release | successful CI on `main` | If root `VERSION` changed and tag is missing, build release binaries, create `vX.Y.Z`, and publish a GitHub Release. |\n\nRelease artifacts include:\n\n- `stellaclaw`\n- `agent_server`\n- `VERSION`\n- `example_config.json`\n\n---\n\n## Repository Layout\n\n```text\n.\n├── agent_server/     # Minimal session process wrapper around stellaclaw_core\n├── core/             # SessionActor, providers, tool catalog, tool executor\n├── stellaclaw/       # Host process, Telegram channel, config, workdir upgrade\n├── ROAD_MAP.md       # Architecture roadmap and implementation notes\n├── VERSION           # Project release version and changelog\n└── example_config.json\n```\n\n---\n\n## Development\n\nUseful checks:\n\n```bash\ncargo fmt --all --check\ncargo test --workspace --locked\ncargo build --workspace --release --locked\n```\n\nWhen changing durable layouts or config schemas, read [AGENTS.md](AGENTS.md) first. It defines the required migration and versioning responsibilities.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\nBuilt with Rust. Designed for durable agents, real conversations, and long-running work.\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeremyguo%2Fclawparty","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeremyguo%2Fclawparty","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeremyguo%2Fclawparty/lists"}