Skip to content
Projects

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.

How these counts are measured

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.

AI

README.md

Original

Timothy

CI codecov Release Go React TypeScript PostgreSQL License: AGPL v3

Timothy

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.

License

AGPL-3.0