Talos

Talos

A self-hosted, vertical Ethereum agent.

Daemon plus thin clients. Curated DeFi tools. Daily-fresh ecosystem knowledge. Bring your own keys. Your wallet never leaves your machine.

---

> In Greek myth, Talos was the bronze automaton forged by Hephaestus to guard the island of Crete — circling its shores three times a day, repelling intruders. This Talos guards your Ethereum positions instead.

What is Talos?

Talos is an opinionated agent for working with Ethereum. It runs locally as an always-on daemon (talosd) with thin clients on top — a CLI REPL, a Telegram bot, and an MCP server you can drop into Claude Desktop, Cursor, or OpenClaw. The daemon owns a single PGLite database, a hot pool of curated DeFi MCP servers, a nightly knowledge cron over the ETH ecosystem, and a wallet that never leaves your machine.

It is vertical by design. General-purpose agents will cheerfully invent contract addresses and miss the difference between Aave and Uniswap. Talos ships with first-party tools for Aave V3, Uniswap V3, Li.Fi, Blockscout, the Coinbase AgentKit, and a generic EVM MCP — all wired through a single tool-routing surface that the agent loop sees as one bundle. Transactions sign locally via viem; nothing leaves the box.

Why Talos?

| Problem | What Talos does | |---|---| | General agents are shallow on DeFi specifics | Curated, namespaced tools per protocol | | Stateless agents forget across sessions | Three-tier memory: hot (last 20 runs) + warm (thread summary) + cold (cross-thread semantic recall) | | Hosted agents take custody of your wallet | Local viem signer, mode-0600 storage, BYOK model keys | | One-shot LLM tools are slow to spin up | Always-running daemon — CLI invocations hit a hot runtime in = 22**

• pnpm >= 9
• An OpenAI API key (BYOK)

Install

git clone https://github.com/Allen-Saji/talos.git
cd talos
pnpm install

> npm publish is on the roadmap — package name TBD because talos collides with Talos Linux on npm.

Initialize

pnpm dev:cli init

The interactive wizard walks you through:

1. OpenAI API key (written to .env, mode 0600)
2. Burner wallet generation (viem mnemonic, exported as private key)
3. Channel configuration (channels.yaml)
4. Daemon bearer token
5. Database migrations
6. Optional service install (launchd / systemd)

Re-running init is idempotent — it detects existing config and prompts to keep or reset. Pass --non-interactive for CI.

Run

# Start the daemon (foreground)
pnpm dev:daemon

# In another terminal, open the REPL
pnpm dev:cli repl

Or production-style, after pnpm build:

talosd &
talos repl

Example interaction

You: what's my wallet address and ETH balance?
↳ calling agentkit_wallet_get_wallet_details
   ✓ 0x13CDAe5a4be3C4b4061eb2206e3dc239aD5F4399 — 0.0086 ETH

You: swap 0.001 ETH for USDC on uniswap, then supply 2 USDC to aave
↳ calling uniswap_get_quote { tokenIn: "ETH", tokenOut: "USDC", amountIn: "0.001" }
   ✓ ~2.59 USDC at 0.3% fee
↳ calling uniswap_swap_exact_in { ... }
   ✓ tx 0x17643319... → confirmed
↳ calling aave_approve_pool { token: "USDC", amount: "2" }
   ✓ tx 0x4b9a... → confirmed
↳ calling aave_supply { token: "USDC", amount: "2" }
   ✓ tx 0x9c2d... → confirmed

Done. Swapped 0.001 ETH for 2.59 USDC and supplied 2 USDC to Aave.
You now have an aUSDC position earning variable yield.

Channels

CLI

talos repl

Thin WebSocket client. ^C aborts the current run, ^D exits. Slash commands (/help, /thread new, /status) handled client-side.

Telegram

Set TELEGRAM_BOT_TOKEN and enable the channel in channels.yaml:

channels:
  telegram:
    enabled: true
    bot_token_ref: env:TELEGRAM_BOT_TOKEN
    allowed_users: ['@yourname']

The bot streams progress edit-in-place — one message per run, throttled to ~1 edit/second to stay under Telegram's rate limit.

MCP server (Claude Desktop, Cursor, OpenClaw)

Talos exposes itself as an MCP server. Drop this into your host's config:

{
  "mcpServers": {
    "talos": {
      "command": "npx",
      "args": ["talos", "serve", "--mcp"]
    }
  }
}

Tools exposed to the host:

| Tool | What it does | |---|---| | query_eth_knowledge | Hybrid retrieval over the local knowledge base; returns chunks + citations | | eth_action | Runs the full Talos agent loop; streams progress to the host as MCP notifications/progress | | eth_status | Wallet, chains, last-sync, enabled MCPs | | talos_new_thread | Resets the host's session thread |

One thread per host session, so calls within a session share continuity. Cross-thread recall bridges to your CLI and Telegram history.

Tool catalogue

| Source | Tools | Mode | |---|---|---| | Aave V3 (Sepolia) | aave_get_user_account_data, aave_approve_pool, aave_supply, aave_borrow, aave_repay, aave_withdraw | native | | Uniswap V3 (Sepolia) | uniswap_get_quote, uniswap_approve_router, uniswap_swap_exact_in | native | | Li.Fi | lifi_get_chains, lifi_get_connections, lifi_get_quote, lifi_get_status, lifi_execute_quote | native | | AgentKit | wallet primitives + Pyth, Compound, Morpho, and more (Coinbase action providers) | MCP-as-source | | Blockscout | multi-chain block, contract, tx reads | hosted MCP (Streamable HTTP) | | mcpdotdirect/evm-mcp | generic EVM RPC, ENS, ERC-20/721 | local MCP |

Adding a tool is an exercise in copying any of the src/tools// folders — contracts.ts, tokens.ts, the action files, source.ts, index.ts. Mutating tools call viem directly from the action file's execute.

Project layout

src/
  runtime/         agent loop, provider router, agent registry
  persistence/     PGLite + Drizzle (threads, runs, steps, embeddings, knowledge)
  memory/          three-tier hot / warm / cold retrieval
  mcp-host/        multi-MCP-client orchestrator with namespacing
  tools/
    aave/          custom Aave V3 source
    uniswap/       custom Uniswap V3 source
    lifi/          Li.Fi cross-chain source
    agentkit/      Coinbase AgentKit cherry-pick
    native/        NativeToolSource base
  knowledge/       nightly cron + retrieval pipeline
  wallet/          viem signer
  init/            `talos init` wizard (idempotent)
  channels/
    cli/           WS REPL client
    telegram/      grammY bot
    mcp-server/    stdio↔WS proxy (Talos-as-MCP)
  daemon/          talosd, control plane WS, lifecycle, doctor, install-service
  protocol/        WS frame zod schemas
  config/          paths, env, token
  shared/          logger, errors

bin/
  talos.ts         CLI entry
  talosd.ts        daemon entry

drizzle/           generated migrations
docs/              spec.md, architecture.md
tests/
  integration/     end-to-end tests against PGLite-in-memory
  eval/            demo-flow regression eval (locked seed, mocked LLM)

Development

pnpm typecheck
pnpm lint
pnpm test
pnpm build

Conventional Commits enforced via commitlint pre-commit hook. Lint and typecheck run on every commit.

The eval suite (pnpm test:eval) runs the locked demo-flow regression against a mocked LLM tape — it verifies that the agent emits the expected MCP tool sequence for a known intent. This is the gate; tools that change behaviour need a fresh tape.

For the full contributor workflow, see [CONTRIBUTING.md](CONTRIBUTING.md).

Status

Built for ETHGlobal Open Agents (Apr 24 – May 6, 2026).

| Layer | State | |---|---| | Runtime + agent loop | shipped | | PGLite persistence + three-tier memory | shipped | | MCP host + namespaced tool surface | shipped | | Channels (CLI, Telegram, MCP server) | shipped | | Native tools (Aave, Uniswap V3, Li.Fi) | shipped | | Hosted MCPs (Blockscout, evm-mcp, AgentKit) | shipped | | Nightly knowledge cron | shipped | | talos init interactive wizard | shipped | | Demo-flow regression eval | shipped | | ZeroDev account-abstraction wrap | deferred to v1.1 |

License

[MIT](LICENSE) © Allen Saji

Acknowledgements

• Vercel AI SDK — agent loop substrate
• Drizzle ORM — schema-as-TS persistence
• PGLite — Postgres-in-WASM, the reason this app fits in a single binary
• viem — Ethereum client
• grammY — Telegram bot framework
• The ETHGlobal Open Agents organisers and judges

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Allen-Saji
• Source: Allen-Saji/talos
• License: MIT
• Homepage: https://talos.allensaji.dev

Install and usage instructions live in the source repository linked above.