Amethyst

One AI interface to your apps, information, tasks and tools.

A local-first personal operating system. One FastAPI backend, one React frontend, one SQLite database — everything stays on your machine.

Python 3.11+ · FastAPI · React 19 · SQLite · MIT

Amethyst runs an agent loop that reasons, acts, and observes — streaming every turn, tracing every tool call, and asking before anything writes or runs. It connects to your calendar, mail, tasks, and files; keeps a searchable Library of everything you save; and works with local models through Ollama for a zero-cost, zero-cloud setup, or with 20+ cloud providers.

Features

Also: Mail (beta, direct Gmail), Automations (beta, a prompt on an interval), a full Activity log, and a tray + global hotkey desktop mode.

Parallel Execution

Amethyst can run multiple data-gathering tasks simultaneously, dramatically speeding up research and data collection:

# Example: Research multiple topics at once
dispatch_parallel_jobs([
  {task: "web_search", params: {query: "AI news"}},
  {task: "web_search", params: {query: "climate change"}},
  {task: "urls", params: {urls: ["https://example.com"]}},
  {task: "github_activity", params: {username: "user"}},
])

Key features:

• Task auto-correction — Common mistakes like fetch_url → urls are automatically fixed
• Error recovery — Clear error messages guide the agent to use correct tools
• Progress tracking — Real-time status updates in the UI
• Smart routing — Fast tasks run locally, slow tasks use remote workers

Available tasks: urls, web_search, gmail, github_activity, git_status, file_info, system_info, briefing, todo, rss

Smart File Reading

Amethyst reads files intelligently, preventing common issues:

• Binary detection — Automatically detects and handles binary files
• Image recognition — Shows images as base64 with metadata
• Hard limits — 50KB max, 2000 lines, 2000 chars per line
• Pagination — Use offset and limit for large files
• Truncation notices — Clearly shows when data is truncated

Example:

view_file("large_file.py", offset=100, limit=50)  # Lines 100-150

LLM Intelligence Rules

The agent follows strict rules to prevent common mistakes:

1. Never guess tool names — Must check available tools before use
2. Never retry failed tools — Must understand why it failed first
3. Never generate fake data — Must tell user honestly what happened
4. Always have fallback strategy — Primary → Alternative → Manual
5. Tool inspection protocol — Mandatory check before every tool call

These rules ensure the agent is reliable and transparent about its capabilities.

The agent, briefly

• Reason → act → observe. The Director picks the tools; you watch it work.
• Operation-level permissions. A prompt names the exact operation — write_file, run_shell_command:read-only vs. destructive — and approving a read never approves a write. Standing approvals can be revoked anytime in Settings.
• Skills are markdown. A skill is a plain SKILL.md file. No plugins, no code lifecycle. Write one in the app, import a link, or install from the catalogue.
• MCP connectors. Any Model Context Protocol server — stdio, SSE, or streamable HTTP — registers into one flat tool registry.
• Parallel execution. Run multiple data-gathering tasks simultaneously with automatic task name correction and error recovery.
• Smart file reading. Binary detection, image handling, pagination, and hard limits prevent token explosion and improve performance.

Quick start

Fastest path (macOS / Linux / WSL2 — Windows: run.bat):

git clone https://github.com/Wayn-Git/Amethyst.git
cd Amethyst
./run.sh

The script sets up the venv, installs dependencies, initializes the database, builds the frontend, and opens http://127.0.0.1:8000.

Docker:

docker compose up

Models in two minutes, no API keys:

# Install Ollama from https://ollama.ai, then:
ollama run llama3.2

Ollama models appear in the chat model selector automatically. Prefer cloud? Add a key to .env (ANTHROPIC_API_KEY, OPENAI_API_KEY, GROQ_API_KEY, …) or run ./run.sh --setup for the interactive wizard. See the Quickstart for the full guide, including OAuth connectors and the Cloudflare relay.

Models

Works with local Ollama out of the box, plus 21 provider presets: OpenAI, Anthropic, Google Gemini, Groq, OpenRouter, xAI, DeepSeek, Mistral, and more — or point providers.yaml at any OpenAI-compatible endpoint.

Security

• Every tool dispatch passes a permission gate; you approve the operation, not just the tool.
• Secrets live in the OS keychain, never in the database.
• State is a local SQLite database (WAL mode); Library files are plain markdown in ~/.amethyst/library/.
• Shell tools run sandboxed; the sandbox and permission system are covered by the test suite.

Documentation

Project layout

backend/     FastAPI app, agent loop, tools, connectors, CLI
  agent/     Director, prompt, tool selector, state management
  tools/     Built-in tools (filesystem, shell, workers, etc.)
  workers/   Parallel job execution, collectors, metrics, templates
frontend/    React 19 + Vite SPA (chat, today, tasks, library, …)
  components/ UI components including ParallelJobCard for job visualization
relay/       Cloudflare Worker: holds Instagram/webhook captures while
             your machine sleeps
agents/      Bundled skills (plain SKILL.md files)
docs/        Guides, architecture notes, screenshots
tests/       53 pytest files — permissions, sandbox, retrieval, streaming

Contributing

PRs welcome. Read CONTRIBUTING.md first — it documents the conventions (one worker, secrets rule, comment philosophy) the codebase holds.

License

MIT