Methoryn

A multi-agent AI assistant that runs on your desktop.

Methoryn is a terminal app (TUI) powered by Groq and Gemini. Groq handles your primary tasks with tool execution and streaming output. Gemini handles parallel sub-tasks in the background. The interface is built with Textual.

Features

• Multi-agent execution — Groq runs your task while Gemini sub-agents handle parallel work
• Tool use — reads/writes files, runs shell commands, searches the web
• 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 /keys set, 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, /gmail, /drive, /save, /copy, /sign-in, and more

Requirements

• Python 3.13+
• A Groq API key — required (free tier available)
• A Google AI Studio API key — optional, enables Gemini sub-agents
• A Google Cloud OAuth2 credentials.json — optional, enables Gmail / Drive / Docs / 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

"Methoryn --help" hangs

• This is normal behavior in versions before 0.1.40
• Methoryn launches a TUI immediately, not a traditional CLI
• Use uv tool list or pip list | grep -i methoryn to verify installation

macOS: "Developer cannot be verified"

• Go to System Settings → Privacy & Security → Allow Anyway (one-time)

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. Get API keys (at minimum, Groq is required):

   • Groq — free tier: 12K tokens/minute
   • Google AI Studio — optional: enables Gemini sub-agents

2. Launch and configure:

   Methoryn
   

   On first run, you'll see a setup screen. Add your Groq API key and optionally sign in with Google.

3. Try your first prompt:

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

API Keys

Methoryn supports five providers, one per agent layer. Only Groq is strictly required for basic operation, but the full multi-layer architecture needs the others.

GOOGLE_ACCOUNT_EMAIL is also read from .env to enable Google Workspace OAuth (Gmail/Drive/Docs/Sheets/Calendar).

You can set any key inside the app without touching .env:

/keys set GROQ_API_KEY your_key_here
/keys list
/keys remove GROQ_API_KEY

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)
│   ├── groq_agent.py       — Main agent (Groq + tool execution)
│   ├── gemini_agent.py     — Sub-agent pool (Gemini + fallbacks)
│   ├── chat_agent.py       — Fast chat responses (Mistral / NVIDIA)
│   ├── code_review_agent.py — Code execution and self-fix
│   ├── state.py            — Shared app state (single source of truth)
│   ├── config.py           — API key loading (.env + BYOK)
│   ├── byok.py             — Bring Your Own Key persistence (~/.Methoryn/byok.json)
│   ├── output.py           — Session save/load (sessions/ folder)
│   ├── file_output.py      — Local file export (.txt .md .html .csv .docx .pdf)
│   ├── google_auth.py      — Google OAuth2 flow (token cached at ~/.Methoryn/)
│   ├── intro.py            — Splash animation
│   └── cli.py              — `Methoryn` command entry point
├── 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

Requires GROQ_API_KEY to be set.

Notes

• Sessions are auto-saved on quit and auto-loaded on next launch so context carries over
• GOOGLE_API_KEY is optional — if absent, Gemini sub-agents are disabled and a warning appears at startup; all other features work normally
• sessions/ and outputs/ are local-only and excluded from git
• Google tokens are stored at ~/.Methoryn/google_token.json, outside the project directory
• BYOK keys are stored at ~/.Methoryn/byok.json — local to the machine, never synced

License

MIT © 2026 Methoryn