gud tek built by a long-time solami dev

Please give us a star if you're interested in seeing this project get fully built out. It will help me gauge interest. Thank you.

TrenchClaw

TrenchClaw is an openclaw-like agentic ai harness and runtime for the Solana blockchain. It's a personal solana assistant that executes modular on-chain actions, runs automated trading routines, and gives operators full visibility and control from our lightweight svelte gui. This is very dangerous and will be a while before security is perfected.

Built on @solana/kit and Bun from the ground up, with GUI/mobile surfaces planned for 1.0. Zero legacy dependencies (including legacy @solana/web3.js v1). Functional, composable, tree-shakeable. Designed for operators who care about what ships in their binary.

Current test requirement keys: helius api key for helius-backed reads, jupiter ultra key for swap flows, and an OpenRouter or Gateway API key for chat-driven workflows.

Full architecture: ARCHITECTURE.md

Translations

• 日本語 / Japanese

v0.1.0 Release Checklist

• AI chat with OpenRouter and Vercel AI Gateway
• Local instance sign-in, vault, and trading settings
• Managed wallet reads for balances and holdings
• Wallet creation, grouping, and renaming
• Helius RPC-based data fetching
• Dexscreener market and token research
• Jupiter Ultra swaps
• Jupiter Trigger API flows
• Queue jobs, scheduled Ultra swaps, and action sequences
• Direct transfers and token account cleanup
• Runtime memory, queue, and conversation history
• Operator chat now prefers token metadata and tickers over mint-only coin answers
• Desktop GUI for chat, wallets, keys, settings, activity, and runtime status
• Full runtime settings editor in the GUI
• Agent-managed scheduler
• Standard swap paths beyond Jupiter Ultra
• Telegram chat connector
• Gatekeeper option for the Helius RPC link

Quick links:

• Quickstart
• Keys and Settings
• Runtime Architecture and Boundaries
• Why TypeScript?
• Why Solana Kit
• TrenchClaw vs ElizaOS and Agent Kit

Interested in sponsoring development? Support us: 7McYcR43aYiDttnY5vDw3SR6DpUxHG8GvLzhUsYFJSyA

Experimental software warning: this is currently unsafe, and unexpected behavior is highly likely if you use it.

Get Started

Use the docs for install and first-run:

• Getting Started

Developer Runtime State

Local development should use the same per-instance runtime shape as the shipped product, while keeping mutable state outside the repo.

Default local dev behavior:

• bun run dev uses ~/.trenchclaw-dev-runtime for runtime state
• generated prompt-support files live under ~/.trenchclaw-dev-runtime/instances/<id>/cache/generated/
• that state persists across reconnects and restarts
• that state is personal/local and never part of the repo

Important rules for contributors, reviewers, and agents:

• do not store personal vaults, wallets, logs, databases, or generated runtime state in this repository
• .runtime/ is the tracked contract only; runtime code must never write there
• the external dev runtime keeps local testing close to a real user install without polluting PRs
• tests should use temporary runtime roots, not a shared developer runtime

Common setup:

# initialize the default external dev runtime once
bun run dev:runtime:init

# start local dev against the persistent external runtime
bun run dev

# copy selected instance state into the external dev runtime
bun run dev:instance:clone -- \
  --from-root /path/to/source-runtime \
  --to-root ~/.trenchclaw-dev-runtime \
  --from-instance 00 \
  --to-instance 00 \
  --parts wallets,db,settings

Useful overrides:

• bun run dev -- --runtime-root /path/to/runtime --generated-root /path/to/runtime/instances/00/cache/generated
• TRENCHCLAW_RUNTIME_STATE_ROOT=/path/to/runtime

The external dev runtime writes a managed .gitignore so secrets, keypairs, databases, logs, caches, and other personal testing state stay out of git by default.

Dashboard UI

Desktop chat, activity feed, wallet controls, settings, and live runtime console in one operator surface.

Runtime Architecture and Boundaries

TrenchClaw is a constrained execution runtime, not a free-form chatbot shell.

The shortest correct model is:

1) Runtime authority

• apps/trenchclaw is the source of truth.
• apps/frontends/gui is a client of the runtime.
• apps/runner packages and launches the runtime plus GUI.

2) Tool system

• Runtime tool definitions live under apps/trenchclaw/src/tools.
• src/tools/registry.ts declares the runtime action tools and workspace tools.
• src/tools/snapshot.ts builds the current tool snapshot from settings, filesystem policy, and release readiness.
• src/ai/gateway/lanePolicy.ts chooses the tool subset for each lane.
• src/runtime/chat/service.ts registers only that selected tool subset with the model.

3) Execution boundaries

• Tools are typed and schema-validated before execution.
• Settings-aware policy checks can block or require confirmation before dangerous actions run.
• Filesystem access is constrained by runtime manifests and instance-scoped roots.
• Workspace escape hatches like workspaceListDirectory, workspaceReadFile, and workspaceBash stay available only when policy allows them.

4) State model

• .runtime is the repo-tracked contract and template area.
• .runtime-state is the live mutable state root.
• Each active instance owns its own settings, vault, wallets, logs, queue state, and workspace.

5) Why this matters

This design keeps the model on a narrow, explicit tool surface while still allowing enough freedom to inspect the runtime workspace and use a constrained shell when needed. The goal is a local operator runtime with auditable state transitions and deliberate machine boundaries, not a vague assistant with broad host access.

Why TypeScript?

The TypeScript repo is heavier than minimalist alternatives. But it is currently the best and most accurate agent orchestrator for this stack. Here is why.

What advanced agents actually require

An "advanced" agent (beyond prompt-in / prompt-out) is mostly state + typed tool I/O + event streaming + orchestration:

1. Tool contracts that are both machine-readable and runtime-validatable — the model needs a schema to decide how to call tools; your runtime needs to validate arguments before executing anything (guardrails). In practice this becomes "JSON Schema everywhere" + a local validator.
2. A first-class event stream — you don't just want final text; you want structured events: partial tokens, tool-call intents, tool args, tool results, retries, errors, traces.
3. Composable middleware — logging, redaction, policy checks, rate limits, caching, retries, circuit breakers, and tool routing.
4. Rapid iteration — agent quality is dominated by iteration speed: schema tweaks, tool UX, prompt/tool descriptions, trace analysis.

That set of needs strongly selects for ecosystems that treat schemas as primary artifacts, JSON as the native interchange, streaming as a first-class API, and web deployment as the default.

Compile-time types + runtime schemas (the missing half in systems languages).

For agents, types alone are insufficient because the LLM must see the contract and your runtime must validate untrusted tool arguments. In the Vercel AI SDK tool model, a tool declares an inputSchema (Zod or JSON Schema) which is both consumed by the LLM (tool selection + argument shaping) and used by the runtime to validate the tool call before execute runs. TypeScript is where this shines:

• Zod is ergonomic to author in TS.
• You can infer TS types from schemas (or vice versa) so the schema and the implementation don't drift.
• You can carry schema objects through routing layers without codegen.

In most systems-language stacks you end up with one of: great static typing but the schema shown to the model is hand-rolled/duplicated, or runtime validation that requires heavy codegen pipelines. Agent code is glue code. Glue code penalizes heavy codegen.

The Vercel AI SDK is TypeScript-first by design.

Vercel positions the AI SDK as "The AI Toolkit for TypeScript." Tool calling (generateText + tool(...)) is a core primitive. AI SDK strict mode behavior (tool schema compatibility, fail-fast semantics) is exactly the production detail you want in advanced agents. If your orchestration is centered on Vercel AI SDK primitives — tools, streams, UI streaming, provider adapters — the lowest-friction native language is TS.

Structural typing + JSON-native payloads + ergonomic transforms.

Agent payloads are structurally shaped objects: tool args, tool results, intermediate plans, traces. TS is effective because structural typing matches JSON shapes, transform pipelines are concise (map/filter/reduce, Zod transforms), and you can model event streams as discriminated unions and exhaustively switch on them (high leverage for agent traces). In systems languages you're constantly bridging between strongly typed structs and dynamic JSON, adding serialization boilerplate and versioning friction.

The JS/TS agent ecosystem is schema-driven by default.

Community patterns converge on "schema as first-class value," and lots of integrations assume Node/TS toolchain. Even if you don't use LangChain, this means schema-oriented integrations are plug-and-play rather than ports.

Why systems languages underperform here

This isn't about raw power — it's about where the complexity lives.

• Agent orchestration is I/O-bound + integration-heavy, not CPU-bound. Most agent loops spend time calling models, calling web APIs, waiting on DB, streaming events to UI, and validating/routing tool calls. That profile does not reward Rust/Zig/C++ the way a tight compute kernel does.
• The hard part is contract evolution, not execution speed. The dominant failure modes are schema drift, tool ambiguity, partial/invalid args, and inability to safely evolve tool signatures. TS + schema-first patterns reduce drift because the schema object is colocated with the code and passed through the system as data. In systems languages the "contract as data" story becomes a build-time artifact (codegen), a separate schema file that can drift, or runtime reflection that's less ergonomic than TS + Zod — all of which increase iteration cost.
• Streaming UX is easier in the JS runtime model. Token streaming, partial structured outputs, tool-call visualizations, reactive UI updates — the Vercel/Next ecosystem is optimized for that workflow and the AI SDK provides those primitives in the same language and runtime as your UI.

Why many Go/Rust agent stacks are a poor fit for this environment

In this repo's environment (AI SDK orchestration + schema-first tools + Solana execution), the main risk is usually unsafe or ambiguous tool behavior, not raw compute throughput.

• AI SDK + Zod is a single control plane in TS. The same schema object drives model-visible tool contracts and runtime validation. In Go/Rust stacks this is usually split across generated types, JSON schemas, and adapter layers, which increases mismatch risk.
• Fast guardrail iteration matters more than compile targets. We frequently adjust tool descriptions, policy checks, confirmation gates, and schema constraints. TS lets these changes land in one place and ship quickly without regeneration/rebinding cycles.
• Wallet and execution safety are runtime-policy problems. Confirmation requirements, amount/notional limits, allowlists, idempotency keys, decision traces, and policy block reasons all live in orchestration/runtime layers. That layer benefits most from TS-native schema + event tooling.
• Most Go/Rust "agent frameworks" optimize for infra shape, not operator safety UX. They can be excellent for service performance, but often require extra custom work to match strict tool schemas, rich stream events, and interactive safety controls expected in trading/operator systems.

Systems languages still fit extremely well behind strict boundaries (signing, parsing, deterministic execution, high-throughput services). They are usually not the fastest path for the orchestrator that must remain tightly coupled to AI SDK tool contracts and streaming UI behavior.

The practical synthesis

The strongest default architecture for this stack is:

TypeScript orchestrator (agent brain) + optional systems-language executors (muscle, only when justified)

• TS owns: tool schemas and validation, orchestration loop and routing, streaming events and UI integration, persistence format/versioning of traces, provider adapters (AI SDK).
• Rust/Zig/Go (optional) own: cryptography-heavy or latency-critical primitives (signing, parsing), sandboxed tool executables, deterministic compute kernels, RPC services behind strict schemas.

This preserves agentic flow (fast iteration, schema-first tooling, Vercel AI SDK integration) while using systems languages only where they actually dominate. If no component is bottlenecked by throughput, latency, or native constraints, an all-TypeScript implementation is usually the simpler and better default.

Why Solana Kit is an advantage in this architecture

@solana/kit is not just a Solana SDK choice here; it improves the same agentic properties this TypeScript stack optimizes for:

• Schema-aligned tool boundaries: Kit's typed RPC, transactions, and signer APIs map cleanly into JSON Schema/Zod-based tool contracts.
• Safer orchestration loops: functional, immutable transaction composition reduces hidden mutation bugs inside multi-step tool pipelines.
• Lower drift risk: strict TS types around accounts, signers, blockhash lifetimes, and lamports (bigint) keep model-selected tool args closer to executable reality.
• Better iteration velocity: composable modular imports and generated clients (Codama) make it faster to add or refine Solana actions without rewriting plumbing.

When TypeScript is effectively required

TS is effectively required when all are true:

1. Orchestration is centered on Vercel AI SDK primitives (tools, streams, strict-mode behavior).
2. Tool contracts evolve rapidly and must stay aligned across model-visible schema, runtime validation, and implementation types.
3. The product depends on streaming-first UX in a Next/Vercel-style deployment surface.

Under these constraints, systems-language orchestrators often re-create TS-native schema + streaming + UI integration layers from scratch.

Why Solana Kit

TrenchClaw does not use @solana/web3.js v1. It uses @solana/kit (formerly web3.js v2), the official ground-up rewrite from Anza.

The old @solana/web3.js is a monolithic, class-based SDK. Its Connection class bundles every RPC method into a single non-tree-shakeable object. Whether you call one method or fifty, your users download the entire library. It relies on third-party crypto polyfills, uses number where bigint belongs, and provides loose TypeScript types that let bugs slip to runtime.

Kit is the opposite. It is functional, composable, zero-dependency, and fully tree-shakeable. It uses the native Web Crypto API for Ed25519 signing instead of userspace polyfills. It uses bigint for lamport values. It catches missing blockhashes, missing signers, and wrong account types at compile time, not after your transaction fails on-chain.

The numbers

Real-world impact: the Solana Explorer homepage dropped its bundle from 311 KB to 226 KB (a 26% reduction) after migrating to Kit.

What changes in practice

No more Connection class. Kit replaces it with createSolanaRpc() and createSolanaRpcSubscriptions() — lightweight proxy objects that only bundle the methods you actually call. Whether your RPC supports 1 method or 100, the bundle size stays the same.

No more Keypair. Kit uses CryptoKeyPair from the Web Crypto API via generateKeyPairSigner(). Private keys never have to be exposed to the JavaScript environment. Signing happens through TransactionSigner objects that abstract the mechanism — hardware wallet, browser extension, CryptoKey, or noop signer for testing.

No more mutable transactions. Kit uses a functional pipe() pattern to build transaction messages. Each step returns a new immutable object with an updated TypeScript type, so the compiler tracks what your transaction has (fee payer, blockhash, instructions, signers) and what it's missing — before you ever hit the network.

import { pipe, createTransactionMessage, setTransactionMessageFeePayerSigner,
  setTransactionMessageLifetimeUsingBlockhash, appendTransactionMessageInstructions,
  signTransactionMessageWithSigners } from '@solana/kit';

const tx = pipe(
  createTransactionMessage({ version: 0 }),
  (tx) => setTransactionMessageFeePayerSigner(payer, tx),
  (tx) => setTransactionMessageLifetimeUsingBlockhash(blockhash, tx),
  (tx) => appendTransactionMessageInstructions([transferInstruction], tx),
);

const signed = await signTransactionMessageWithSigners(tx);

No more hand-rolled instruction builders. Program interactions use generated clients from Codama IDL files. Drop an IDL JSON in lib/client/idl/, run codegen, get typed instruction builders, account decoders, PDA helpers, and error enums. TrenchClaw imports from these generated clients — never constructs instructions manually.

TrenchClaw vs ElizaOS and Agent Kit

If you are evaluating Solana agent stacks today, the practical split is this: TrenchClaw is built directly on @solana/kit, while many existing agent ecosystems still rely on legacy @solana/web3.js integrations.

Cross-framework context (same benchmark source)

Storage: Bun SQLite

TrenchClaw uses Bun's built-in SQLite (bun:sqlite) for runtime jobs, receipts, policy/decision traces, market/cache data, and chat persistence (conversations, chat_messages). It keeps state local, restart-safe, and dependency-light.

Schema is Zod-first and auto-synced on boot:

• Central persistence contracts + shared primitives: src/contracts/persistence.ts
• Runtime row schemas: src/runtime/storage/sqliteSchema.ts
• Runtime payload/state schemas: src/runtime/storage/schema.ts
• SQL table/index contract + boot sync + drift inspection: src/runtime/storage/sqliteOrm.ts
• Runtime prints a compact schema snapshot at boot for operator/model context

Runtime log/data layout is split by purpose under src/ai/brain/db/:

• runtime/: SQLite DB + runtime event files
• sessions/: session index + JSONL transcript stream
• summaries/: compact per-session markdown summaries
• system/: daily system/runtime logs
• memory/: daily + long-term memory notes

Why this stack here

Solana Kit, Jupiter integration, and Codama-generated clients are all TypeScript-native in this repo. Bun gives fast startup, strong HTTP performance, and native TypeScript execution while keeping the codebase in one language.

What It Does

• Registers and dispatches typed Solana actions with policy gates, retries, and idempotency
• Ships managed wallet reads, wallet management, Dexscreener research, Jupiter Ultra swaps, and direct wallet execution flows
• Composes explicit action sequences, queued jobs, and narrow scheduled swap flows without a broad trigger framework
• Persists runtime state, chat history, and receipts in Bun SQLite so local sessions survive restarts
• Uses RPC, Jupiter, and token-account adapters so the runtime stays provider-agnostic
• Generates typed program clients from Anchor IDLs via Codama instead of hand-rolled instruction builders

The current public release does not promise a broad autonomous strategy engine yet. Scheduling and queued jobs are the current automation surface; broader strategy automation and non-Ultra public swap paths are still coming.

Local Setup

Install dev tooling

Use the dev-only runner bootstrap script to install or upgrade the local development toolchain:

sh ./apps/runner/scripts/bootstrap-dev-tools.sh

That helper manages:

• Bun
• Solana CLI
• Helius CLI

Public standalone installs do not require Bun, Solana CLI, or Helius CLI for first launch. Install those CLIs only when a workflow explicitly needs them.

# Bun (macOS/Linux)
curl -fsSL https://bun.sh/install | bash

# Solana CLI via Anza installer (macOS/Linux, stable channel)
sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"

# Helius CLI
bun add -g helius-cli@latest

# verify installs
bun --version
solana --version
helius --version

# update commands
bun upgrade
agave-install update
bun add -g helius-cli@latest

Run the app locally

Use one command to start the runtime and GUI together:

bun install
bun run app:build
bun run start

What bun run start does:

• Starts the dedicated runner (apps/runner) which then starts the core runtime process (apps/trenchclaw runtime:start)
• Rebuilds missing instance-scoped generated artifacts under .runtime-state/instances/<id>/cache/generated/ on startup, and you can force a full refresh with TRENCHCLAW_BOOT_REFRESH_CONTEXT=1 / TRENCHCLAW_BOOT_REFRESH_KNOWLEDGE=1
• Starts runtime API on localhost
• Serves GUI from static apps/frontends/gui/dist
• Proxies /api/* from GUI server to runtime server
• Prompts launch GUI now? and opens browser after Enter (type skip to keep runtime CLI-only)
• Supports bun run start -- doctor for local preflight checks

Local GUI development still uses Vite:

bun run gui:dev

License

TBD

use at your own risk