# `alix`
[](https://github.com/Alex6323/alix/actions/workflows/ci.yml)
[](https://codecov.io/gh/Alex6323/alix)
[](https://crates.io/crates/alix)
[](https://docs.rs/alix)
[](https://crates.io/crates/alix)
> **Early WIP.** Deck and persisted-state formats still change before 1.0,
> without runtime compatibility paths. Expect resets between commits and keep
> an independent backup for study history you care about.
`alix` is a plain-text spaced-repetition learning tool that turns your own
material into decks you study, then has you prove you actually grasped it, not
just memorized it. It uses AI only where that helps: generating decks from a
source you bring (an article, a paper, a codebase), a tutor on any card, and an
exam that grades your written answers against that source. Reviewing runs fully
offline; you work through several **degrees of depth**, from recognizing an
answer to reconstructing it from memory, and only passing that exam marks a deck
as understood.
**Manual → [alix.study/book](https://alix.study/book/) · Slides → [alix.study/slides.html](https://alix.study/slides.html) · Site → [alix.study](https://alix.study)**
**Feedback → bugs via the [issue form](https://github.com/Alex6323/alix/issues/new/choose), security reports via [`SECURITY.md`](SECURITY.md), ideas at [contact@alix.study](mailto:contact@alix.study)**
## Install
```sh
cargo install alix
# or a prebuilt binary:
The core needs nothing else. The AI features (`generate`, `deck augment`, the
exam, and the tutor) shell out to a model CLI you
install and log in to yourself: [Claude Code](https://www.anthropic.com/claude-code)
by default, or Gemini, Codex, or Copilot via `[ask] backend`. Each backend gets
read-only tools only, and `alix` stores no API keys. See
[Getting started](docs/book/src/02-getting-started.md) and
[Configuration](docs/book/src/16-configuration.md).
## Quick start
```sh
# make decks and workspaces from your own material
alix generate <url-or-file> # -> a deck
alix generate <repo> --goal "how X works" --workspace ~/decks/topic # -> a workspace
# then study, always in the web app (pick a deck or workspace, then a depth)
alix
```
## A deck is a text file
```text
## What does a String own?
A Vec<u8>, its bytes on the heap.
> Capacity can exceed its length.
## Fill in the blank
let \blank{mut} x = 0;
```
The front is the `## ` line; the plain lines below are the answer. A `> ` line
is a note shown after you answer, and a `<!-- -->` directive on a card tunes it
(here `\blank{mut}` turns into a fill-in-the-blank, auto-detected as a cloze
card). Full format and every directive:
[the deck format](docs/book/src/03-the-deck-format.md),
[directives](docs/book/src/07-directives.md).
Math stays editable LaTeX in the deck: write `$a^2 + b^2 = c^2$` inline, or put
`$$\int_0^1 x\,dx = \frac{1}{2}$$` on a whole line for a centered equation.
The web and mobile review clients render the same self-contained formula, while
grading and card identity keep using the source text.
## Commands
| `alix` | Open the web app to pick a deck or workspace |
| `alix profile` | Define and launch a named instance per person (decks, port, kids/adult) |
| `alix generate <source>` | Draft a deck, a trace (`--trace`), or a whole workspace |
| `alix deck augment <deck> --target …` | Add distractors, notes, or key points |
| `alix deck copy\|move <deck> <workspace>` | Transfer one deck and its owned files between workspaces |
| `alix workspace init <dir>` | Scaffold an empty workspace to grow into |
| `alix workspace update <dir>` | Stage a source-aware card update; inspect it, then `--apply` |
| `alix workspace deadline <dir> [<date>\|clear]` | Show, set, or clear a workspace's "ready by" date |
| `alix <dir>` | Serve a folder or workspace as its own scoped instance |
| `alix deck import <file.tsv>` | Import an Anki TSV export (`--workspace` places it) |
| `alix stats <path>` · `alix list <path>` | Progress · schedules (deck, folder, or workspace) |
| `alix reset <path>` | Clear stored progress (deck, folder, or workspace) |
| `alix share <path>` · `alix receive <code>` | Send/get decks over [magic-wormhole](https://magic-wormhole.readthedocs.io) |
| `alix config` | Show the config (`--init` writes a starter file) |
| `alix doctor [path]` | Check the setup, or lint a deck; `--backends` probes the AI |
Every flag and option: [command reference](docs/book/src/17-command-reference.md).
## What's inside
Each links to its chapter in the manual:
- **Reveal methods and session depths** (Recognize / Recall / Reconstruct),
picked per session. → [Reveal & session depths](docs/book/src/04-review-modes.md)
- **FSRS scheduling**, with card retirement and per-deck completion states.
→ [Scheduling](docs/book/src/05-scheduling.md)
- **A tutor** you can ask "why is that the answer?" without leaving review.
→ [The tutor](docs/book/src/10-tutor.md)
- **Deck generation and augmentation** from a URL or a local source (distractors,
notes, key points). → [Generating decks](docs/book/src/11-generating-decks.md)
- **An AI exam** that grades open questions against the source and gates unlocks.
→ [The AI exam](docs/book/src/12-the-ai-exam.md)
- **Traces**: predict-and-verify walks along one path through real source.
→ [Trace decks](docs/book/src/13-trace-decks.md)
- **Workspaces and `explore`**: group decks with shared settings, or turn a
source (including a repo) into an ordered workspace of decks and traces.
→ [Workspaces](docs/book/src/08-workspaces.md), [Explore](docs/book/src/14-explore.md)
- **A local web app** for review and the exam, LAN-shareable, no accounts or
database. → [The web app](docs/book/src/15-the-web-app.md)
- **Self-contained, portable decks.** Decks, frozen assets, and generated
augmentation travel together. Progress is colocated by default for cloud
drive or Syncthing use, or can stay in a private user-files root, no accounts.
→ [Configuration](docs/book/src/16-configuration.md)
- **A personal deadline on a workspace**, with scheduling that leans toward it
and a readiness readout. → [Workspaces](docs/book/src/08-workspaces.md)
- **A paired phone** can borrow your desktop's AI for the tutor and the exam,
over your LAN. → [Pairing a device](docs/book/src/19-pairing.md)
## Development
```sh
make check # clippy + tests, the gate before a change is done
make fmt # format (nightly rustfmt, not plain cargo fmt)
make web # run the web frontend
```
Building a client? The web JSON API is a documented contract:
[docs/API.md](docs/API.md). See [CONTRIBUTING.md](CONTRIBUTING.md).
## Support
alix is free and open source. Telling someone who studies is the best
support; if you want to support the project financially, you can do so
[here](https://github.com/sponsors/Alex6323).
## License
Licensed under either of
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
<http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or
<http://opensource.org/licenses/MIT>)
at your option.
Bundled third-party assets (fonts) are separately licensed; see
[NOTICE](NOTICE).
### Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.