Genesis Agent — Ship a specialized agent.

Philosophy

Build your agent, not the infrastructure.

Every capable agent needs the same core: model wiring, tool calling, retries, memory, guardrails, a console, deployment. Rebuilding it for each project costs weeks before any real work. genesis freezes that core — tuned, tested, and kept current as the field moves — so the latest capabilities are already there when you reach for them.

The foundation — done for you

A complete agent core

Providers: OpenAI · Anthropic · OpenRouter · offline Ollama
Automatic tool discovery from tools/*.py + web search
The agent loop, retries, usage limits, model tuning
Memory + auto-compaction, JSON / SQLite state store
Sandbox, tool policy, human approvals, server auth
Telegram & WhatsApp gateways · built-in scheduler
Live console · HTTP + SSE service · Docker · cron

~8k lines of readable Python on Pydantic AI — small enough to read in a sitting, simple enough to trust in production.

What you build

Only what's yours

persona.md — who your agent is
tools/*.py — what it can do
settings.yaml — how it behaves
.env — which model powers it

That's the complete list. A trading desk, a research bot, a support automation — same foundation, a different agent on top.

Capabilities

The base keeps up. You don't have to.

New agent patterns land in the base as the field moves — opt-in and lean by default. No add-ons to wire, nothing to retrofit.

Planning & delegation

An explicit todo scratchpad for multi-step work, plus sub-agents that take isolated subtasks and report back.

Multimodal input

Drag an image or PDF into the console, or send a URL to the service — vision-capable models see it.

Self-improvement

It can write its own skills and tools into the workspace — validated, sandboxed, and gated by human approval.

Memory that scales

Conversation memory with auto-compaction and a cross-run state store — context stays lean on any model size.

Safe by default

Filesystem sandbox, tool allow/deny policy, human confirmation for risky calls, usage limits, bearer-token server auth.

Any model, any runtime

Switch providers with one .env edit. Run in a terminal, as an HTTP service, in Docker, or on a schedule.

Messaging gateways

Chat with your agent from Telegram or WhatsApp — per-user sessions, deny-all access control, media in, approval buttons. No SDK, built into the core.

Agent-managed scheduling

Ask for recurring work in chat — the agent schedules it, jobs fire in the background, and results are delivered to every channel.

Web-aware

Built-in web_search (no API key) plus a URL fetcher that returns readable text — current info without extra wiring.

How it works

From base to your agent in minutes.

Start from the base

One install command, or run the wizard — agent --new scaffolds a fresh agent in its own folder, foundation included.

Describe the role

Write what your agent is in persona.md — plain markdown, no framework code to learn.

Drop in tools

Any documented, type-hinted function in tools/ is auto-discovered. No wiring, no registration.

Quickstart

Up and running in minutes.

Two ways in — both end at a guided first-run setup that configures your provider, model, and key. No file editing.

01 Fastest — one command

# Windows (PowerShell) — paste in an empty folder

> irm https://raw.githubusercontent.com/ysz7/genesis-agent/main/scripts/install.ps1 | iex; .\start.cmd

# Linux / macOS

$ curl -LsSf https://raw.githubusercontent.com/ysz7/genesis-agent/main/scripts/install.sh | sh && ./start.sh

02 Step by step — clone it yourself

$ git clone https://github.com/ysz7/genesis-agent.git
$ cd genesis-agent
$ ./scripts/install.sh   # installs uv + dependencies
$ ./start.sh             # first launch configures it

No API key? Pick Ollama in the setup — fully offline, nothing to sign up for.