Learn with Ari: Set Up a Local AI Tutor for Pen-and-Paper Study

What Ari Does

Ari is a local AI tutor designed for learning with pen and paper. You can discuss a subject with Ari, receive a curriculum or individual lessons, work through exercises on paper, ask questions while studying, and submit your completed work for grading.

Ari is especially suited to subjects such as mathematics and physics, where solving problems by hand can support deeper learning. Because it runs locally, Ari can use your local Codex login and subscription allowance without requiring an API key.

How the Learning Workflow Works

1. Open Talk with Ari and describe what you want to learn.
2. Discuss the proposed learning outline and adjust it through conversation.
3. Choose Create lesson or Create curriculum.
4. Open the Study desk and work through the exercises on paper.
5. Ask questions whenever you need help.
6. Submit your work for grading when you are ready.
7. Save a reflection so Ari can adapt to your progress.

For example, you could ask: “Teach me photography from scratch, in 20-minute sessions.” New learners begin with a brief conversation to establish context.

Prerequisites

To run Ari locally, install the following:

• Node.js 24 or newer
• Git
• FFmpeg
• A ChatGPT account

The built-in camera bridge works only on Mac. Browser cameras and photo uploads do not require the camera bridge.

Install and Run Ari

Clone the repository and install its dependencies:

git clone https://github.com/nichochar/ari.git
cd ari
npm ci

Install the specified Codex CLI version globally:

npm install -g @openai/codex@0.163.0

Configure Codex to store credentials locally, then sign in through your browser:

codex -c 'cli_auth_credentials_store="file"' login

After completing sign-in, Ari can use the local Codex login and your subscription allowance. An API key is not required for this setup.

Create your environment file, build the application, and start it:

cp .env.example .env
npm run build
npm start

Open http://127.0.0.1:3001 in your browser.

Configure Models

Ari's models are configurable in .env. Make sure your account has access to any model you select. If a configured model is unavailable to your account, choose a model your account supports before using Ari.

Use Cameras and Photos

A camera positioned above your page allows Ari to see the work you are writing. The built-in camera bridge is available on Mac, while browser camera access and photo uploads can be used without it.

The live camera preview remains local. When you deliberately submit work, the submitted photo and relevant learning context are sent to OpenAI for tutoring.

Personalize Ari

Ari uses two core personalization files in ~/.ari/workspace/:

• TUTOR.md defines Ari's teaching style and personality.
• USER.md stores information about the learner.

The memories/ directory contains detailed notes. Ari reads the two core files on each turn and retrieves other notes when needed. These files evolve automatically, but you can also edit them directly or revise them by chatting with Ari.

Use Settings to edit or restore the core documents, browse memories, and manage personalization. Existing learner notes and reflections are imported automatically.

Preview Onboarding Separately

To test the onboarding experience with a separate fresh learner without resetting your existing progress, run:

npm run onboarding

This preview runs on port 3002. Stop it with:

PORT=3002 npm run stop

Understand Your Local Data

Chats, progress, uploaded materials, and submitted photos are saved on your computer under .local/, which Git ignores. Personalization is stored under ~/.ari/workspace/.

Ari is a single-user local application. Keep it on localhost. Although the live camera preview stays local, deliberately submitted work and relevant learning context are sent to OpenAI for tutoring.

Back Up and Restore Learning Data

Create a backup with:

npm run backup

The backup includes learning data, native conversation history, and personalization files, but excludes credentials. Keep the SQLite file and its companion directories together.

Personalization backups also include a matching .workspace directory containing TUTOR.md, USER.md, memories, and the workspace identity marker. The repository does not include .env, credentials, backups, or personal learning data.

To restore a backup, stop Ari and restore the SQLite file, its .codex companion when present, and the .workspace contents to their original locations. The workspace location is saved in the database, so preserve the workspace identity marker.

If the backup command reports that notes differ from their recorded revisions, open Settings to refresh those edits and try the backup again.

Development Commands

For development, start the UI with:

npm run dev

The development UI runs on port 5173. Run the test suite with:

npm test

Create a production build with:

npm run build

Brand and logo guidance is available in design/README.md.

Conclusion

Ari combines handwritten problem solving with an AI tutor that can create learning plans, answer questions, grade submitted work, and adapt through reflections and stored learner context. Once Node.js, Git, FFmpeg, and Codex are configured, you can run the tutor locally and build a study workflow around paper, a camera, and guided practice.