Methoryn

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

Methoryn is a terminal app (TUI) built on a five-layer AI orchestration stack, one specialised agent per layer:

You type one prompt; Groq turns it into a task plan, Cloudflare executes it with deterministic library scripts, and the specialist agents handle their lanes automatically. The interface is built with Textual.

Features

• Five-layer agent stack — Groq plans, Cloudflare executes libraries, Gemini handles multimodal work, Mistral writes code, NVIDIA verifies
• 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 Cloudflare API key + account ID — optional, enables Layer 2 library management
• A Google AI Studio API key — optional, enables Gemini (Layer 3)
• A Mistral API key — optional, enables the coding agent (Layer 4)
• An NVIDIA NIM API key — optional, enables quality control (Layer 5)
• 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
   • Cloudflare — optional: enables Layer 2 library management
   • Google AI Studio — optional: enables Gemini (Layer 3)
   • Mistral — optional: enables the coding agent (Layer 4)
   • NVIDIA NIM — optional: enables quality control (Layer 5)

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)
│   ├── cli.py               — `Methoryn` command entry point
│   ├── groq_agent.py        — Layer 1: Conversation & Orchestration (Groq)
│   ├── cloudflare_agent.py  — Layer 2: Library Manager (Cloudflare)
│   ├── gemini_agent.py      — Layer 3: Multimodal & Research (Gemini)
│   ├── mistral_agent.py     — Layer 4: Coding Agent (Mistral)
│   ├── nvidia_agent.py      — Layer 5: Quality Control (NVIDIA)
│   ├── inter_agent_protocol.py — Agent-to-agent protocol + TaskPlan
│   ├── task_plan.py         — TaskPlan parsing / delegation helpers
│   ├── 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
│   ├── setup_screen.py      — First-run API key setup
│   ├── taskbar.py           — Taskbar progress indicator
│   └── widgets.py           — MainBox, SideBar, SlashPalette, PromptEditor
├── 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
• Optional keys (Cloudflare, Gemini, Mistral, NVIDIA) disable only their layer — 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