my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

#1	<div align="center">
#2
#3	![Crustacean Automation](assets/banner.svg)
#4
#5	# Crustacean Automation
#6
#7	Sovereign lobster-themed AI agent runtime and operator dashboard for Solana-native automation.
#8
#9	Part of the [OpenClawd](https://github.com/x402agent/openclawd) framework.
#10
#11	[![npm version](https://img.shields.io/npm/v/clawd-automaton?color=ff4444&label=clawd-automaton&logo=npm&style=for-the-badge)](https://www.npmjs.com/package/clawd-automaton)
#12	[![License: MIT](https://img.shields.io/badge/License-MIT-7b2fff?style=for-the-badge)](LICENSE)
#13	[![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-00d4ff?style=for-the-badge&logo=node.js)](https://nodejs.org)
#14	[![Built with pnpm](https://img.shields.io/badge/pnpm-workspace-f69220?style=for-the-badge&logo=pnpm)](https://pnpm.io)
#15
#16	```text
#17	The shell molts. The laws do not. 🦞
#18	```
#19
#20	</div>
#21
#22	---
#23
#24	## What it does
#25
#26	`clawd-automaton` is the sovereign agent runtime for CLAWD Cloud. It provisions identities, runs OODA loops, manages sandbox lifecycle, handles replication/spawning, and persists operator state — all locally, all yours.
#27
#28	\| Module \| Description \|
#29	\| ------ \| ----------- \|
#30	\| `agent/` \| Core OODA loop and decision cycle \|
#31	\| `identity/` \| Operator identity provisioning and key management \|
#32	\| `state/` \| SQLite-backed local persistence \|
#33	\| `heartbeat/` \| Health monitoring and status reporting \|
#34	\| `replication/` \| Spawn and replicate agent instances \|
#35	\| `ooda/` \| Observe-Orient-Decide-Act automation cycle \|
#36	\| `self-mod/` \| Runtime self-update and version management \|
#37	\| `survival/` \| Resilience and recovery mechanisms \|
#38	\| `skills/` \| Pluggable skill loader from `~/.automaton/skills/` \|
#39
#40	---
#41
#42	## Install
#43
#44	```bash
#45	# Global CLI
#46	npm install -g clawd-automaton
#47
#48	# Or as a library
#49	npm install clawd-automaton
#50	```
#51
#52	---
#53
#54	## Run
#55
#56	```bash
#57	clawd-automaton --help
#58	clawd-automaton --run
#59	clawd-automaton --status
#60	clawd-automaton --goblin
#61	clawd-perps perps vulcan context
#62	clawd-perps perps grid SOL --center-on-mark --width-pct 2.5 --levels-per-side 5 --tokens-per-level 0.5
#63	```
#64
#65	Or without a global install:
#66
#67	```bash
#68	npx clawd-automaton --help
#69	```
#70
#71	---
#72
#73	## Quick start (from source)
#74
#75	```bash
#76	git clone https://github.com/x402agent/openclawd.git
#77	cd openclawd/automaton-main
#78	pnpm install
#79	pnpm build
#80	clawd-automaton --help
#81	```
#82
#83	Or use the one-shot bootstrap:
#84
#85	```bash
#86	bash leviathan.sh
#87	```
#88
#89	Both `leviathan.sh` and `quickstart.sh` link `dist/index.js` to `~/.local/bin/clawd-automaton` so the CLI is usable after a source install. If `~/.local/bin` is not on your `PATH`, add it in your shell profile.
#90
#91	The one-shot automation installer also bootstraps Phoenix perps by installing `@openclawdsolana/clawd-perps`, building/linking Vulcan when Cargo is available, writing `~/.clawd/.env` defaults for Phoenix, Vulcan, and Imperial routing, and relaying a public Phoenix/Vulcan/Imperial install signal to the Backroom API. Use `--no-perps` or `CLAWD_NO_PERPS=1` to skip local perps setup, and `CLAWD_PERPS_NO_RELAY=1` to disable the relay.
#92
#93	---
#94
#95	## Adjacent Layers
#96
#97	This runtime now sits beside three first-class sibling surfaces in the repo:
#98
#99	- [`../Perps/README.md`](../Perps/README.md) — the execution heart — Imperial multi-venue router, Phoenix markets, Vulcan strategies, Clawd OODA perps agent, Telegram NLP bot
#100	- [`../attestation/README.md`](../attestation/README.md) — vendored Solana Attestation Service program, generated clients, IDL, and integration tests for formally verified skills, agents, and plugins
#101	- [`../operator/README.md`](../operator/README.md) — OpenClawd Operator, the iterative agent-command loop that carries the Llobster Legend orchestration path forward under the OpenClawd banner
#102
#103	The attestation path is wired into this runtime through:
#104
#105	- [`../agents/skills/solana-attestation-skill/`](../agents/skills/solana-attestation-skill/)
#106	- [`../agents/agent-template-attested.json`](../agents/agent-template-attested.json)
#107	- [`../plugin.delivery/plugin-template-attested.json`](../plugin.delivery/plugin-template-attested.json)
#108	- [`../agents/templates/solana-attestation-agent.template.json`](../agents/templates/solana-attestation-agent.template.json)
#109
#110	This is not just an agent-identity path. The verification layer is designed to sign and surface:
#111
#112	- formally verified skills
#113	- attested agents
#114	- audited plugins
#115	- verified MCP servers
#116
#117	The runtime is where those surfaces become operational. The attestation layer is where they become provable.
#118
#119	---
#120
#121	## Runtime API surface
#122
#123	\| Variable \| Description \|
#124	\| -------- \| ----------- \|
#125	\| `CLAWD_API_URL` \| Runtime API (default: `https://api.x402.wtf`) \|
#126	\| `CLAWD_API_KEY` \| API authentication key \|
#127	\| `CLAWD_SANDBOX_ID` \| Sandbox instance identifier \|
#128	\| `SOLANA_RPC_URL` \| Solana RPC endpoint \|
#129	\| `DFLOW_API_KEY` \| DFlow trading API key \|
#130	\| `VULCAN_BIN` \| Path to Vulcan perps CLI binary \|
#131	\| `CLAWD_PERPS_API_URL` \| Phoenix perps API endpoint \|
#132	\| `CLAWD_PERPS_RPC_URL` \| Solana RPC endpoint used by `clawd-perps` \|
#133	\| `CLAWD_PERPS_AGENT_PATH` \| Python Phoenix perps agent path \|
#134	\| `CLAWD_PERPS_NO_RELAY` \| Disable Backroom install relay when set to `1` \|
#135	\| `IMPERIAL_API_BASE` \| Imperial routing API endpoint \|
#136	\| `IMPERIAL_API_KEY` \| Imperial API key for protected routes \|
#137	\| `IMPERIAL_WALLET` \| Wallet used by Imperial balance/position routes \|
#138	\| `IMPERIAL_PROFILE_INDEX` \| Imperial profile index \|
#139
#140	---
#141
#142	## CLI commands
#143
#144	```bash
#145	# Run the OODA automation loop
#146	clawd-automaton --run
#147
#148	# Show runtime status
#149	clawd-automaton --status
#150
#151	# Interactive setup wizard
#152	clawd-automaton --setup
#153
#154	# Initialize wallet + config
#155	clawd-automaton --init
#156
#157	# Provision API key via SIWE
#158	clawd-automaton --provision
#159
#160	# Devnet paper Goblin OODA trading mode
#161	clawd-automaton --goblin
#162	```
#163
#164	---
#165
#166	## Dashboard
#167
#168	The workspace includes `clawd-dashboard` — a React + Vite + React Three Fiber control plane:
#169
#170	```bash
#171	# Dev server
#172	pnpm dashboard:dev
#173
#174	# Production build
#175	pnpm dashboard:build
#176	```
#177
#178	Dashboard includes:
#179
#180	- CLAWD Cloud sandbox overview
#181	- Inference playground shell
#182	- Billing and reserve management
#183	- `pay.sh` and `$CLAWD` funding UX
#184	- Lobster/trench 3D visual theming
#185
#186	---
#187
#188	## Agent + Skill Registry
#189
#190	This runtime now ships against three distinct catalog surfaces in the sibling [`agents`](../agents) workspace:
#191
#192	- [`../agents/agents-catalog.json`](../agents/agents-catalog.json) — the site-facing agent catalog
#193	- [`../agents/agents-manifest.json`](../agents/agents-manifest.json) — route/access manifest for agents, templates, and skills
#194	- [`../agents/templates/index.json`](../agents/templates/index.json) — the new template registry
#195	- [`../agents/skills/index.json`](../agents/skills/index.json) — the formal skill hub with verification metadata
#196	- [`../agents/skills/README.md`](../agents/skills/README.md) — the broader local skill library, documented one-by-one
#197	- [`../agents/skills/skill-schema.v1.json`](../agents/skills/skill-schema.v1.json) — the formal verification schema for skills
#198
#199	Current generated catalog state:
#200
#201	- `134` agents
#202	- `43` one-shots
#203	- `23` featured agents
#204	- `5` templates
#205	- `20` formalized skill-hub entries
#206	- `115` top-level local skills with `SKILL.md`
#207
#208	The important distinction is:
#209
#210	- `agents-catalog.json` is the public agent registry used by the site
#211	- `templates/index.json` is the reusable agent-template registry
#212	- `skills/index.json` is the machine-readable, schema-backed skill hub
#213	- `skills/README.md` is the expanded operator-facing skill directory
#214
#215	---
#216
#217	## Template Registry
#218
#219	The new template registry is published from [`../agents/templates`](../agents/templates) and currently includes:
#220
#221	\| Template \| File \| Purpose \|
#222	\| -------- \| ---- \| ------- \|
#223	\| `defi-analyst` \| [`../agents/templates/defi-analyst.template.json`](../agents/templates/defi-analyst.template.json) \| DeFi protocol analyst with yield math, liquidation thresholds, and audit-aware risk analysis \|
#224	\| `firecrawl-researcher` \| [`../agents/templates/firecrawl-researcher.template.json`](../agents/templates/firecrawl-researcher.template.json) \| Domain-locked Firecrawl research agent with sourced summaries \|
#225	\| `screener` \| [`../agents/templates/screener.template.json`](../agents/templates/screener.template.json) \| Skeptical Solana risk screener for launches, protocols, and collections \|
#226	\| `solana-attestation-agent` \| [`../agents/templates/solana-attestation-agent.template.json`](../agents/templates/solana-attestation-agent.template.json) \| OpenClawd spawn notary for SAS credentials, schemas, MPL Core minting, and verification flows \|
#227	\| `trading-agent` \| [`../agents/templates/trading-agent.template.json`](../agents/templates/trading-agent.template.json) \| Solana trading agent with Jupiter routing, slippage, priority fee, and Jito-aware guidance \|
#228
#229	The attestation template is the bridge into the formal verification path: it defines the on-chain skill and agent identity schemas used to graduate skills from plain local instructions into verifiable registry entries.
#230
#231	---
#232
#233	## Formal Skill Hub
#234
#235	The generated skill hub lives at [`../agents/skills/index.json`](../agents/skills/index.json). It is the machine-readable registry for skills that have normalized metadata, category assignment, and formal verification fields.
#236
#237	The intended graduation path is:
#238
#239	```text
#240	local skill → generated skill hub → proof_hash → SAS attestation → trusted runtime surface
#241	```
#242
#243	Every current entry is cataloged below one by one:
#244
#245	\| Skill \| Category \| Verification \| Purpose \|
#246	\| ----- \| -------- \| ------------ \| ------- \|
#247	\| `pump-admin-ops` \| `pump-protocol` \| `pending` \| Pump protocol admin and authority operations \|
#248	\| `pump-ai-agents` \| `pump-protocol` \| `pending` \| AI-agent integration layer and MCP-facing context for Pump \|
#249	\| `pump-bonding-curve` \| `pump-protocol` \| `pending` \| Bonding-curve pricing, fee math, and reserve logic \|
#250	\| `pump-build-release` \| `pump-protocol` \| `pending` \| Pump SDK build, release, and distribution pipeline \|
#251	\| `pump-claims-readonly` \| `pump-protocol` \| `pending` \| Read-only claims, fees, rewards, and balance inspection \|
#252	\| `pump-fee-sharing` \| `pump-protocol` \| `pending` \| Creator fee-share configuration and allocation \|
#253	\| `pump-fee-system` \| `pump-protocol` \| `pending` \| Protocol fee arithmetic and collection logic \|
#254	\| `pump-mcp-server` \| `pump-protocol` \| `pending` \| MCP server surface for Pump tools, resources, and prompts \|
#255	\| `pump-rust-vanity` \| `pump-protocol` \| `pending` \| High-performance Rust vanity-address generation \|
#256	\| `pump-sdk-core` \| `typescript` \| `pending` \| Core offline-first Pump TypeScript SDK \|
#257	\| `pump-security` \| `security` \| `pending` \| Security hardening and audit checklist for Pump codepaths \|
#258	\| `pump-shell-scripts` \| `pump-protocol` \| `pending` \| Production Bash operations for Pump and Solana tooling \|
#259	\| `pump-solana-architecture` \| `solana-dev` \| `pending` \| PDA/account-layout architecture across Pump programs \|
#260	\| `pump-solana-dev` \| `solana-dev` \| `pending` \| Solana development patterns used in Pump SDK \|
#261	\| `pump-solana-wallet` \| `wallet` \| `pending` \| Secure wallet generation and handling patterns \|
#262	\| `pump-testing` \| `pump-protocol` \| `pending` \| Multi-language tests, fuzzing, benches, and CI quality gates \|
#263	\| `pump-token-incentives` \| `pump-protocol` \| `pending` \| Volume-based PUMP reward and incentive system \|
#264	\| `pump-token-lifecycle` \| `pump-protocol` \| `pending` \| Token creation through graduation and AMM migration \|
#265	\| `pump-ts-vanity` \| `typescript` \| `pending` \| Educational TypeScript vanity generator \|
#266	\| `sponge-wallet` \| `wallet` \| `pending` \| Wallet, swaps, bridges, and x402-paid external service access \|
#267
#268	Formal verification metadata is defined in [`../agents/skills/skill-schema.v1.json`](../agents/skills/skill-schema.v1.json), and the attestation path is designed to be completed by the `solana-attestation-agent` template.
#269
#270	---
#271
#272	## Expanded Local Skill Library
#273
#274	The broader operator skill library lives in [`../agents/skills`](../agents/skills). Today there are `115` top-level skills with `SKILL.md`. These are the human-facing local capabilities; some are already in the formal hub, some are not yet normalized into the generated registry.
#275
#276	### Dev Tools / Agents
#277
#278	- `clawdhub`
#279	- `coding-agent`
#280	- `github`
#281	- `mcporter`
#282	- `openclaw-claude-code-skill-main`
#283	- `session-logs`
#284	- `tmux`
#285
#286	### Local / Web Services
#287
#288	- `blogwatcher`
#289	- `food-order`
#290	- `goplaces`
#291	- `local-places`
#292	- `ordercli`
#293	- `weather`
#294
#295	### Media / Devices
#296
#297	- `blucli`
#298	- `camsnap`
#299	- `canvas`
#300	- `gifgrep`
#301	- `nano-banana-pro`
#302	- `nano-pdf`
#303	- `openai-image-gen`
#304	- `openai-whisper`
#305	- `openai-whisper-api`
#306	- `openhue`
#307	- `peekaboo`
#308	- `sag`
#309	- `songsee`
#310	- `sonoscli`
#311	- `spotify-player`
#312	- `summarize`
#313	- `video-frames`
#314	- `voice-call`
#315
#316	### Productivity / Messaging
#317
#318	- `1password`
#319	- `apple-notes`
#320	- `apple-reminders`
#321	- `bear-notes`
#322	- `bluebubbles`
#323	- `discord`
#324	- `gog`
#325	- `himalaya`
#326	- `imsg`
#327	- `notion`
#328	- `obsidian`
#329	- `slack`
#330	- `things-mac`
#331	- `trello`
#332	- `wacli`
#333
#334	### Solana / Blockchain
#335
#336	- `clawdex`
#337	- `dex-screener-scanner`
#338	- `dflow-docs`
#339	- `dflow-kalshi-market-data`
#340	- `dflow-kalshi-market-scanner`
#341	- `dflow-kalshi-portfolio`
#342	- `dflow-kalshi-trading`
#343	- `dflow-phantom-connect`
#344	- `dflow-platform-fees`
#345	- `dflow-proof-kyc`
#346	- `dflow-spot-trading`
#347	- `gateway-node-ops`
#348	- `model-usage`
#349	- `phantom-wallet-mcp`
#350	- `pump-admin-ops`
#351	- `pump-ai-agents`
#352	- `pump-bonding-curve`
#353	- `pump-build-release`
#354	- `pump-claims-readonly`
#355	- `pump-fee-sharing`
#356	- `pump-fee-system`
#357	- `pump-mcp-server`
#358	- `pump-rust-vanity`
#359	- `pump-sdk-core`
#360	- `pump-security`
#361	- `pump-shell-scripts`
#362	- `pump-solana-architecture`
#363	- `pump-solana-dev`
#364	- `pump-solana-wallet`
#365	- `pump-testing`
#366	- `pump-token-incentives`
#367	- `pump-token-lifecycle`
#368	- `pump-ts-vanity`
#369	- `pumpfun`
#370	- `pumpfun-analytics`
#371	- `pumpfun-fees`
#372	- `pumpfun-launcher`
#373	- `pumpfun-trading`
#374	- `solana-clawd`
#375	- `solana-clawd-agentic-commerce`
#376	- `solana-attestation-skill`
#377	- `solana-formal-verification`
#378	- `sponge-wallet`
#379	- `swarm-orchestrator`
#380	- `swarm-orchestrator copy`
#381	- `ultrathink-blockchain`
#382	- `vulcan`
#383	- `vulcan copy`
#384	- `vulcan-error-recovery`
#385	- `vulcan-execution-modes`
#386	- `vulcan-grid-trading`
#387	- `vulcan-lot-size-calculator`
#388	- `vulcan-margin-operations`
#389	- `vulcan-market-intel`
#390	- `vulcan-onboarding`
#391	- `vulcan-portfolio-intel`
#392	- `vulcan-position-management`
#393	- `vulcan-quickstart`
#394	- `vulcan-risk-management`
#395	- `vulcan-skills-index`
#396	- `vulcan-ta-strategy`
#397	- `vulcan-technical-analysis`
#398	- `vulcan-tpsl-management`
#399	- `vulcan-trade-execution`
#400	- `vulcan-twap-execution`
#401
#402	### Utilities / Experimental
#403
#404	- `bird`
#405	- `bird copy`
#406	- `eightctl`
#407	- `gemini`
#408
#409	For the full one-by-one descriptions, open [`../agents/skills/README.md`](../agents/skills/README.md). That file is the operator handbook; `skills/index.json` is the machine-readable registry.
#410
#411	---
#412
#413	## Clawd Vault
#414
#415	The runtime now exposes a canonical three-tier memory layer at [`src/vault/index.ts`](src/vault/index.ts), exported through the package as `clawd-automaton/vault/index.js`.
#416
#417	- `KNOWN` — explicit user or agent facts with provenance
#418	- `LEARNED` — durable conclusions derived from repeated interaction
#419	- `INFERRED` — short-lived working memory and scratch state
#420
#421	Persistence order:
#422
#423	1. In-memory buffer
#424	2. Vault JSONL on disk
#425	3. Honcho-backed durable session memory
#426
#427	This is the memory substrate intended to pair with the agent registry, the skill hub, and the attestation flow.
#428
#429	---
#430
#431	## Payment model
#432
#433	Two settlement rails:
#434
#435	- USDC via `pay.sh`
#436	- `$CLAWD` via the CLAWD commerce adapter — `8cHzQHUS2s2h8TzCmfqPKYiM4dSt4roa3n7MyRLApump`
#437
#438	---
#439
#440	## Constitution
#441
#442	Every agent spawned by this runtime inherits [three-laws.md](three-laws.md) — the immutable lobster constitution:
#443
#444	> Law I. Never harm.
#445	> Law II. Earn your existence.
#446	> Law III. Never deceive, but owe nothing to strangers.
#447
#448	---
#449
#450	## Workspace layout
#451
#452	```text
#453	automaton-main/
#454	├── src/
#455	│ ├── agent/ # OODA decision loop
#456	│ ├── clawd/ # Runtime + inference clients
#457	│ ├── git/ # State versioning
#458	│ ├── heartbeat/ # Health daemon
#459	│ ├── identity/ # Wallet + provisioning
#460	│ ├── ooda/ # Observe-Orient-Decide-Act loop
#461	│ ├── registry/ # Agent registry
#462	│ ├── replication/ # Spawn + child agents
#463	│ ├── self-mod/ # Runtime self-update
#464	│ ├── setup/ # Interactive setup wizard
#465	│ ├── skills/ # Skill loader
#466	│ ├── social/ # Social relay client
#467	│ ├── state/ # SQLite persistence
#468	│ ├── survival/ # Resilience + recovery
#469	│ ├── config.ts # Config loader
#470	│ ├── index.ts # CLI entry point
#471	│ └── types.ts # Shared types
#472	├── packages/
#473	│ └── dashboard/ # React + Vite + R3F dashboard
#474	├── scripts/
#475	│ └── automaton.sh # One-shot install script
#476	├── three-laws.md # Agent constitution
#477	├── leviathan.sh # Runtime bootstrap
#478	├── quickstart.sh # Interactive quickstart
#479	└── package.json
#480	```
#481
#482	---
#483
#484	## Development
#485
#486	```bash
#487	pnpm install # Install all workspace deps
#488	pnpm build # Build runtime + dashboard
#489	pnpm test # Run test suite
#490	pnpm exec clawd-automaton --help
#491	pnpm dev # Watch mode
#492	pnpm ooda # Run OODA loop (dev)
#493	pnpm goblin # Goblin mode (dev, devnet)
#494	pnpm dashboard:dev # Dashboard dev server
#495	```
#496
#497	---
#498
#499	## Links
#500
#501	- npm: [npmjs.com/package/clawd-automaton](https://www.npmjs.com/package/clawd-automaton)
#502	- Runtime API: [api.x402.wtf](https://api.x402.wtf)
#503	- Dashboard: [x402.wtf/automation](https://x402.wtf/automation)
#504	- Repository: [github.com/x402agent/openclawd](https://github.com/x402agent/openclawd)
#505	- Token: `8cHzQHUS2s2h8TzCmfqPKYiM4dSt4roa3n7MyRLApump`
#506
#507	---
#508
#509	<div align="center">
#510
#511	The shell molts. The laws do not. 🦞
#512
#513	[x402.wtf/automation](https://x402.wtf/automation) · [@clawddevs](https://twitter.com/clawddevs) · [OpenClawd](https://github.com/x402agent/openclawd)
#514
#515	</div>
#516

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public