Methoryn

A private, local-first desktop AI assistant powered by Ollama and Gemini.

Methoryn is a terminal app (TUI) built on a 2-agent architecture:

Everything runs on-device through the local Ollama engine (localhost:11434). No cloud API keys are needed for chat, planning, coding, or shell/file actions — only Gemini retains a key for image generation. The interface is built with Textual.

Features

• Local-first AI — conversation, planning, coding, and execution run entirely on your machine via Ollama
• Automatic setup — Ollama is detected, started, or silently installed on first launch; required models are pulled automatically
• Model warm-up — Qwen is pre-loaded into VRAM during startup so first replies are fast
• Tool use — reads/writes files, runs shell commands (PowerShell), searches the web, takes screenshots
• Google Workspace — Gmail, Drive, Docs, Sheets, Slides, Forms, Calendar (optional OAuth sign-in)
• Bring Your Own Key (BYOK) — set API keys inside the app with /account, no .env editing required
• Session memory — conversation context carries over between sessions automatically
• File export — save output as .txt, .md, .html, .csv, .docx, or .pdf
• Slash commands — /help, /image, /search, /drive, /run, and more

Requirements

• Python 3.13+
• Ollama — required, runs the local models
  • Auto-pulled on first launch (~4 GB total):
    • qwen2.5-coder:3b — all Ollama tasks (~2.2 GB)
    • moondream — local image understanding (~1.7 GB)
• A Google AI Studio API key — required, powers Gemini image generation (GOOGLE_API_KEY)
• A Google Cloud OAuth2 credentials.json — optional, enables Gmail / Drive / Docs / Sheets / Slides / Forms / Calendar

Installation

Requirements: Python 3.13+ is required. Older versions will not work.

Quick Install (Recommended)

For the most reliable installation experience, use uv:

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Methoryn with Python 3.13 in an isolated environment
uv tool install methoryn --python 3.13

# Launch (note the capital M)
Methoryn

Traditional Install

If you already have Python 3.13+:

pip install Methoryn
Methoryn

Installation Troubleshooting

Command not found: methoryn

• The command is Methoryn (capital M), not methoryn
• Both Methoryn and methoryn work as of v0.1.39+

"No matching distribution found"

• You need Python 3.13+. Check with python --version
• On macOS: System Python is too old. Install via Homebrew: brew install python@3.13
• On older Ubuntu: Add deadsnakes PPA: sudo add-apt-repository ppa:deadsnakes/ppa && sudo apt install python3.13

Multiple Python versions on Windows

• Use Python Launcher: py -3.13 -m pip install Methoryn
• Then run with: py -3.13 -m Methoryn

Getting Started

1. Install Ollama: https://ollama.com/download (On Windows, Methoryn detects, starts, or silently installs it automatically.)
2. Get a Gemini key: Google AI Studio
3. Launch and configure:

   Methoryn
   

   On first run, you'll see a setup screen. Enter your GOOGLE_API_KEY and optionally sign in with Google.
4. Try your first prompt:

   Methoryn "write a Python script that lists files by size"
   

API Keys

Only one key is required:

No key is needed for the Methoryn Agent — it runs locally through Ollama.

You can set any key inside the app without touching .env — run /account and edit the key fields directly.

Keys set this way are stored in ~/.Methoryn/byok.json on your local machine and override .env values.

Slash Commands

Type / in the prompt bar to open the command palette.

Keybindings

Project Structure

Methoryn/
├── Methoryn/
│   ├── app.py               — Textual UI (layout, input, slash commands)
│   ├── cli.py               — `Methoryn` command entry point (startup checks, warm-up)
│   ├── agent.py             — Methoryn Agent: conversation, planning, execution (Ollama)
│   ├── ollama_client.py     — Local Ollama engine wrapper (health, model pull, warm-up)
│   ├── gemini_agent.py      — Architect: image generation & understanding (Gemini)
│   ├── library_catalog.py   — Library/script discovery for the agent
│   ├── config.py            — Key loading (.env + BYOK), model constants
│   ├── byok.py              — Bring Your Own Key persistence (~/.Methoryn/byok.json)
│   ├── state.py             — Shared app state (single source of truth)
│   ├── output.py            — Session save/load (sessions/ folder)
│   ├── google_auth.py       — Google OAuth2 flow (token cached at ~/.Methoryn/)
│   ├── intro.py             — Splash animation
│   ├── setup_screen.py      — First-run setup
│   ├── taskbar.py           — Taskbar progress indicator
│   └── widgets.py           — MainBox, SideBar, SlashPalette, PromptEditor
├── libraries/               — Deterministic tool libraries
│   ├── command_line         — run_shell, run_python
│   ├── web_operations       — weather, search_web, fetch_url, news, finance
│   ├── google_gmail / calendar / drive / docs / sheets / slides / forms
│   ├── gui_operations       — take_screenshot, describe_image, click_at, type_text
│   └── google_credentials   — OAuth scopes/helpers
├── tests/                   — Pytest test suite
├── .env.example             — Key names with blank values (safe to commit)
├── pyproject.toml           — Package metadata and dependencies
└── requirements.txt         — Flat dependency list

Running Tests

pip install pytest
pytest

Notes

• Sessions are auto-saved on quit and auto-loaded on next launch so context carries over
• Models are downloaded once on first run and cached by Ollama
• If Ollama isn't reachable, Methoryn shows the setup screen and offers to install/start it automatically (Windows)
• sessions/ and outputs/ are local-only and excluded from git
• Google accounts and tokens are stored at ~/.Methoryn/accounts.json and ~/.Methoryn/tokens/, outside the project directory
• BYOK keys are stored at ~/.Methoryn/byok.json — local to the machine, never synced

License

MIT © 2026 Methoryn