Armin

Armin is a local-first, spaced-repetition flashcard app for desktop. It's built around the idea that learning is hierarchical. You should master the prerequisites of a topic you are trying to learn in order to understand it fully.

For more on the philosophy of what inspired this type of thinking, read this Justin Skycak's article on learning prerequisites.

Table of Contents

• What it is
• Why it exists
• Core principles
• Installation
  • Linux
  • Windows
  • macOS
• Releases
• MCP server
• Card-writing skill
• Development notes
• Contributions

What it is

A desktop study app where you create decks and cards (like Anki), connect cards by their prerequisites, and review them on a schedule that adapts to how well you actually remember each one. Reviews are powered by FSRS (Free Spaced Repetition Scheduler), the same algorithm used by Anki's FSRS mode.

Why it exists

Most flashcard apps treat every card as an independent atom of knowledge, meaning all cards always live in the same level of abstraction. In practice, knowledge is a graph: some things are prerequisites for others. Armin makes that structure explicit. A card stays locked until everything it depends on has been learned, so you build foundations before tackling what sits on top of them, and new material lands on knowledge you've already secured.

Core principles

• Local-first. Everything works offline; your data lives on your machine. No account, no server required.
• Spaced-repetition done right. FSRS schedules each card based on your recall performance.
• Hierarchical knowledge. Within a deck, cards form a prerequisite graph. You review the prerequisites first, then unlock and learn what builds on them. Each deck has its own visual canvas that lets you see and edit the connections between its cards; prerequisites never cross deck boundaries.
• Simple UI & UX. Creating decks, cards, and tags should be fast, and reviewing should be keyboard-driven and frictionless.
• AI-assisted card creation. Armin exposes a local MCP server, so you can use your own AI agent (Claude Code, Codex, OpenCode, etc.) to generate flashcards from a topic, your notes, or research. It also comes with an agent skill that guides agents on which guidelines they should use for creating cards. It is important not only to be able to create the cards, but to make sure the content aligns with what you are actually are trying to learn and it is structured in an effective manner for future studying.
• Open-source. Fully open, MIT-licensed, and meant to be built on.

Installation

Each release is published on GitHub. You can find them in the Releases section.

Linux

Download the Armin-*-x64.AppImage, make it executable, and run it:

chmod +x Armin-*-x64.AppImage
./Armin-*-x64.AppImage

Optional: import the AppImage with Gear Lever for a desktop entry.

Windows

Download and run the Setup.exe file for your release. It is an unsigned beta installer. Microsoft Defender SmartScreen may warn that it has no established reputation. This is expected: Armin does not yet have a paid Windows code-signing certificate. Download it only from this project's GitHub Releases, then use SmartScreen's More info and Run anyway controls if you trust the release.

Some managed PCs and Windows security policies do not permit unsigned apps to run. Armin cannot bypass those policies.

macOS

Download the ZIP that matches your Mac:

• arm64 for Apple silicon Macs (M1 and later)
• x64 for Intel Macs

Unzip it and move Armin.app to Applications. Armin is an unsigned beta app and is not notarized because the project does not yet have a paid Apple Developer membership. Gatekeeper will warn on first launch. If you trust the download from this project's GitHub Releases, try to open Armin once, then go to System Settings → Privacy & Security and choose Open Anyway. macOS saves that choice for future launches.

Do not disable Gatekeeper or other system security features to run Armin.

Releases

Alpha builds are published from GitHub tags. See docs/release.md for the release checklist, artifact targets, and current unsigned-build notes.

MCP server

Armin includes a local stdio MCP server so coding agents can create decks, cards, and prerequisite graphs. See docs/mcp-server.md for setup, available tools, and configuration for Codex, Claude Code, Cursor, and OpenCode.

Card-writing skill

The MCP server lets agents create cards, but it doesn't tell them how to structure the content — how to chunk a topic, what belongs in a single card, or how cards should depend on each other. The writing-study-cards skill provides those guidelines, distilled from Andy Matuschak's How to write good prompts. Install it so your agent applies them automatically whenever it generates cards.

The skill lives in .agents/skills/writing-study-cards and installs with the skills CLI:

# Install into the current project (auto-detects your agent)
npx skills add ansanabria/armin --skill writing-study-cards

# Or install globally so it's available across all projects
npx skills add ansanabria/armin --skill writing-study-cards --global

You can target a specific agent (for example Cursor, Claude Code, or Codex) with -a, and preview what's available without installing using --list:

npx skills add ansanabria/armin --list
npx skills add ansanabria/armin --skill writing-study-cards -a cursor

The skills CLI discovers skills under .agents/skills/, so it picks up writing-study-cards directly from this repository.

Development notes

Early development. Expect lots of bugs and strange behavior.

See docs/testing.md for the testing philosophy, test-layer guidance, and validation commands used in this codebase.

Contributions

Bug reports and feature requests are very welcome — file them in the Issues tab. They're the most useful thing you can send at this stage.

Code pull requests aren't being accepted yet: the domain model and internal contracts are still moving quickly. This will open up as the project stabilizes. See CONTRIBUTING.md for details, and SECURITY.md to report a vulnerability privately. Participation is governed by our Code of Conduct.