timothy-agent/timothy
timothy-agent/timothy has 61 GitHub stars and 11 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-18 08:10 UTC. Last push 2026-11-12.
What you can do
- One assistant, every model - Nebius Token Factory (NVIDIA Nemotron), Anthropic, OpenAI, Amazon Bedrock, DeepSeek, GLM, local models via Ollama, or any compatible provider, all behind one interface. Pick which model handles chat, coding, research, decisions, or briefings, and let Timothy fail over to a backup when a provider has a bad day.
- Give it real work - Hand Timothy a task (research a topic, write a report, fix a bug) and it works unattended: plans, executes, verifies its own output, and shows you the result with a full timeline of what it did. Quick tasks skip the ceremony and just get done.
- Results find you - Any task or schedule can deliver its result to Telegram, email, a webhook, or GitHub (a pushed branch or an opened pull request) the moment it finishes, files attached. No checking a dashboard: the answer lands where you already are.
- Your daily briefings - Wake up to a digest of your inbox, calendar, and spending, delivered to Telegram or email in your timezone, saying only what actually needs your attention. Schedule any task to run on your clock.
Measured star growth
- in 24h
- 0
- in 7 days
- Collecting history
- in 15 days
- Collecting history
- in 1 month
- Collecting history
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
The open-source control plane for your personal AI workforce. Run your own AI agents. Your infrastructure. Your models. Your rules.
AIREADME.md
OriginalTimothy

The open-source control plane for your personal AI workforce. Run your own AI agents. Your infrastructure. Your models. Your rules.
Timothy runs on your hardware and works for you around the clock. Shape agents with their own model, tools and knowledge, hand them real work, and let them chat, research, write code, read your inbox and calendar, and brief you about what matters. They remember who you are across every conversation and deliver results to your phone while you sleep. Every conversation, memory, document, and API key stays on infrastructure you control.
Use any model you want: Nebius Token Factory (NVIDIA Nemotron), Anthropic, OpenAI, Amazon Bedrock, DeepSeek, GLM, a local Ollama, or any compatible endpoint. Route each kind of work to whichever model does it best, switch anytime from settings, no code changes, no lock-in.
Status: alpha, under active development.
Alpha releases with prebuilt images are available on the Releases page; expect rough edges and breaking changes between releases.
Features
| Feature | What you get |
|---|---|
| One assistant, every model | Nebius Token Factory (NVIDIA Nemotron), Anthropic, OpenAI, Amazon Bedrock, DeepSeek, GLM, local models via Ollama, or any compatible provider, all behind one interface. Pick which model handles chat, coding, research, decisions, or briefings, and let Timothy fail over to a backup when a provider has a bad day. |
| Give it real work | Hand Timothy a task (research a topic, write a report, fix a bug) and it works unattended: plans, executes, verifies its own output, and shows you the result with a full timeline of what it did. Quick tasks skip the ceremony and just get done. |
| Results find you | Any task or schedule can deliver its result to Telegram, email, a webhook, or GitHub (a pushed branch or an opened pull request) the moment it finishes, files attached. No checking a dashboard: the answer lands where you already are. |
| It writes code safely | Coding tasks run in an isolated sandbox with the toolchains each repo pins (Go, Node, Python, Java, PHP, Ruby, Rust), on their own git branch, with the work verified before you see it. It can also hand the coding work to a CLI agent you already use, Claude Code, Codex, Cursor, opencode, or pi, while keeping review and budgets in your hands. |
| Your daily briefings | Wake up to a digest of your inbox, calendar, and spending, delivered to Telegram or email in your timezone, saying only what actually needs your attention. Schedule any task to run on your clock. |
| Connected to your life | Gmail, Google Calendar, Docs, Drive, GitHub, Outlook, IMAP, CalDAV, and any MCP server. Timothy reads them when a task needs it, and asks before doing anything destructive. |
| Shape your own assistants | Create named agents with their own personality, favorite model, and exactly the tools and knowledge they need, nothing more. A briefing agent that reads only your mail and calendar can never touch your code or send a message on your behalf. |
| It remembers you | Preferences, projects, and facts you share carry across conversations, and recurring patterns become insights over time. You approve what becomes a standing instruction; noise gets filtered before it ever reaches you. |
| Your documents, searchable | Drop in files or URLs; Timothy files them into topic collections and uses them to answer your questions. Your own knowledge base, on your own disk. |
| Nothing gets lost | Conversations survive restarts, crashes, and upgrades. Pick up any session exactly where it left off. |
| You control the spend | Every model call is priced and logged honestly. Set budgets with alerts, see exactly where the money goes, and route routine work to cheap or free models. |
| Private by design | Runs entirely on your hardware. Sensitive content like email can be pinned to a local model so it never leaves your network, and API keys live in an encrypted store (or your own Vault / AWS Secrets Manager), never in logs, never in the UI. |
| Talk to it | Optional voice input with fully local speech-to-text. Audio never leaves your machine. |
A day with Timothy
Things Timothy's own operator actually runs it for:
- 07:00, your phone buzzes. "Two things need you today: the client call at 14:00 has an unanswered thread from yesterday, and your card was charged twice by the same vendor. The other 14 emails were newsletters." A scheduled briefing read your inbox and calendar, cross-referenced them, and messaged you on Telegram.
- "Find every receipt from my Portugal trip and total it per currency." Timothy searches your Gmail, opens each receipt (never trusting a snippet), and reports an itemized breakdown with per-currency totals it computed with a calculator, not vibes.
- "Research the current EU AI Act timeline and write me a cited summary." It searches the web, reads primary sources, writes the report to a file, and a verification step checks the artifact exists and cites real URLs before you ever see "done".
- "Fix the flaky test in my repo." A coding mission clones the repo into a sandbox, works on its own branch, runs the tests, and opens the result for your review. Your laptop stays untouched.
- "Remember that Ana owes me EUR 200 from dinner, she'll pay in September." Weeks later: "Who owes me money?" answers correctly, because facts you tell it persist and stay retrievable.
- Drop a PDF into the knowledge base. It lands in the right topic collection automatically, and next week "what did that scaling article say about probabilistic counting?" quotes it back.
- Every evening at 20:00, an expense digest lists the day's spending from your inbox; every Monday at 07:00, a week-prep note cross-references your calendar with recent email threads and flags meetings that need preparation.
Each of these is a schedule, a chat message, or a one-line task. No plugins to write, no pipelines to build.
Role-based model routing
Timothy's gateway decouples agent roles from specific model providers, so you can route high-frequency background work to fast, low-cost open models and reserve frontier reasoning models for deep missions—with automatic catalog pricing and per-call cost tracking in the ledger.
For example, running a full open-weights stack on Nebius Token Factory (https://api.tokenfactory.nebius.com/v1) with NVIDIA Nemotron models:
| Role / route | Workload | Example model on Nebius Token Factory |
|---|---|---|
decide |
Selects mission kind (coding vs general), light vs full mode, and auto-route |
nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B |
summarize |
Extracts background memory facts, classifies KB collections, compacts sessions | nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B |
default |
Handles interactive chat, web research, and tool calls | nvidia/nemotron-3-super-120b-a12b |
coding |
Plans, builds, and verifies multi-phase coding and research missions | nvidia/Nemotron-3-Ultra-550b-a55b |
Each route supports ordered fallback targets across providers (e.g., failing over between Nebius Token Factory, local Ollama, OpenRouter, Anthropic, or Bedrock) without changing agent or mission code.
Architecture
Go microservices behind a single public API, one PostgreSQL database, React web UI. All run via Docker Compose.
| Service | Role |
|---|---|
brain |
Public API: chat orchestration, agent loop, missions, event-sourced sessions, SSE streaming |
gateway |
Internal LLM gateway: multi-provider routing, cost ledger |
memoryd |
Internal memory service: pgvector-backed recall |
sandboxd |
Internal service running per-mission sandboxes: Docker containers on Compose, pods on Kubernetes |
cliproxy |
Internal proxy: wraps ChatGPT Plus/Pro and Claude subscriptions into OpenAI-compatible API on :8317 |
web |
React + Tailwind interface: chat, missions, usage, settings |
searxng |
Internal metasearch backend for search_web (profile search, full; Tavily also supported) |
markitdown |
Internal Python sidecar: file→markdown conversion (profile docs, full) |
ocr |
Internal Python sidecar: tesseract image OCR (profile docs, full) |
whisper |
Internal Python sidecar: local speech-to-text for the web mic button (profile whisper, full) |
pdfgen |
Internal Python sidecar: markdown→PDF via Typst for chat, mission export (profile docs, full) |
Timothy defaults to a lightweight core footprint (~300–500 MiB RAM: brain, gateway, memoryd, sandboxd, cliproxy, web, postgres). Heavy Python sidecars and SearXNG run under opt-in Compose profiles (search, docs, whisper, or full to enable all; ~6–10 GiB RAM total). Web search also natively supports Tavily as a cloud backend without running the SearXNG sidecar.
Plus Postgres (18 + pgvector), internal only, no host port. Migrations are embedded in each Go binary and applied automatically at startup; there's no separate migrate command. Every Go service exposes GET /health and GET /metrics; brain's /metrics, the only one on a published port, requires Authorization: Bearer $TIMOTHY_METRICS_TOKEN.
Sessions are an append-only event log: every turn, tool run, and compaction is an immutable event, so conversations survive crashes mid-stream and replay exactly as they happened.
Published ports (everything else is compose-internal):
| Port | What |
|---|---|
3300 |
Web UI |
8300 |
Brain (public API) |
8317 |
CLIProxyAPI (Subscription proxy) |
3301 |
Vite dev server (make dev) |
Published ports serve plain HTTP and are meant for a trusted LAN. For any exposure beyond that, put a reverse proxy in front that terminates TLS. Authentication uses HttpOnly, SameSite=Strict post-quantum hybrid session cookies (or TIMOTHY_API_TOKEN bearer authentication for CLI and automations). The web UI ships a Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, and Referrer-Policy: strict-origin-when-cross-origin; a proxy that rewrites response headers should preserve them.
Quick start (prebuilt images)
The fastest way to run Timothy: no Go/Node toolchain, no build step, just Docker and the released images.
curl -fsSL https://raw.githubusercontent.com/timothy-agent/timothy/main/deploy/release/install.sh | sh
The installer resolves the newest release, installs into ~/timothy (override with TIMOTHY_HOME=/some/dir), generates a .env with fresh secrets (POSTGRES_PASSWORD, TIMOTHY_MASTER_KEY, TIMOTHY_API_TOKEN), pulls the images, and starts the core lightweight stack. Open http://localhost:3300/ to complete the first-run admin account setup.
Prefer to inspect scripts before running them? Every release also ships install.sh as an asset: download it from the releases page, read it, then sh install.sh.
Everything else about running Timothy lives in the docs: timothy-agent.github.io/docs.
Documentation
| Topic | Where |
|---|---|
| Requirements, quick start, build from source | Install |
| Upgrading, pending schema changes | Upgrade |
| Backups and restoring onto a fresh host | Backup and restore |
| Sign in, welcome wizard, first chat, first mission | First run |
| Agents, routes, missions, memory, knowledge, automations | Concepts |
| Gmail, GitHub, Telegram and the rest | Connectors and channels |
| Every settings tab and field | Settings reference |
| Something broke | Troubleshooting |
Local development
The Go toolchain runs fully containerized; no host Go install required.
make build # compile everything
make test # unit tests
make vet # go vet
make lint # golangci-lint
Frontend development with hot reload:
make dev # Vite dev server on :3301, proxies /v1 to brain
make test-integration, make canary, and make kb-eval (retrieval eval harness, scripts/kb-eval/) need the compose stack up (make up first).
Design decisions are documented as D-0XX markers in code comments next to the code they explain.