ALO — Agentic Learning OS

Turn any folder into a learning workspace.

ALO is a local-first CLI/TUI for building a personal learning system around any subject. It keeps your profile, roadmap, lessons, weaknesses, reviews, and progress in Markdown files you can read, edit, and commit.

Quick Install

pip install alo-learning-os
alo

Check the installation:

alo version
alo doctor

(Note: The PyPI distribution name is alo-learning-os. The installed command is alo.)

Why ALO?

Most learning starts with enthusiasm and then disappears into scattered notes, unfinished tutorials, lost context, too many tabs, and generic study plans with no real review loop or progress history.

ALO’s answer is simple:

• One folder per subject
• Markdown state files
• A personal roadmap tailored to you
• Daily focused learning sessions
• Built-in review loop for your weaknesses
• Safe Git history to track progress

What It Feels Like

pip install alo-learning-os
mkdir my-python-learning
cd my-python-learning
alo

The workflow is straightforward. You can use the interactive dashboard (alo) or direct CLI commands: init → config → paths → roadmap → learn → review → sync

Terminal Preview

$ alo doctor
Checks Python, Git, workspace status, and LLM readiness.

$ alo paths
Generates learning path options based on your profile.

$ alo learn
Starts a focused learning session from the current roadmap.

(Screenshots and a short demo GIF are planned).

Workspace File Tree

Nothing is hidden in a database. Nothing is locked inside a web app. The workspace is just files.

my-python-learning/
├─ learning-profile.md
├─ skill-map.md
├─ learning-paths.md
├─ roadmap.md
├─ weaknesses.md
├─ progress-log.md
├─ tutor-rules.md
└─ privacy-rules.md

What ALO is not

• Not a course marketplace
• Not a hosted learning platform
• Not a notes app
• Not a chatbot skin

ALO is the layer that keeps your learning process organized.

Who It’s For

• Developers learning new stacks
• Designers learning product/UX
• Product managers building structured knowledge
• Students who want versioned learning notes
• Self-learners who want a review loop

Workspace Files

These are normal Markdown files. You own them. You can read them. You can edit them. You can commit them.

LLM Configuration

ALO supports LLM-assisted features for generating personalized roadmaps and lessons.

Safe API Guidance:

• Recommended: keyring mode (stores securely in your OS credential manager)
• Alternative: env mode (reads from an environment variable name)
• Never paste keys into Markdown
• Never commit keys

Example for OpenAI-compatible providers:

Provider: openai-compatible
Base URL: https://api.example.com/v1
Model: gpt-4o-mini
Storage: keyring

Git Sync Safety

ALO takes Git sync seriously to prevent accidental secret leaks or unwanted file tracking.

• ALO never uses git add .
• Only known learning files are staged.
• Unsafe staged files block sync.
• Secret-looking content blocks commits.
• Dry-run is available.

alo sync --dry-run
alo sync --no-push

Commands

Mock Mode / Offline Demo

Mock mode is useful for trying the workflow without an API key.

alo paths --mock
alo roadmap --mock
alo learn --mock
alo review --mock

Roadmap

See v1.1.0 planning for the next milestone.

• Now: workspace README generator, learning stats, progress charts, streaks
• Later: roadmap import, examples gallery, richer dashboard UX

(Note: roadmap.sh-compatible import is future research, not current functionality.)

Current Limitations

• Python 3.12+ only
• LLM features require a configured provider unless mock mode is used
• Screenshots/GIF are not added yet
• Direct roadmap.sh integration is not implemented yet

Security

Please refer to SECURITY.md for vulnerability reporting instructions.

Do not paste API keys into issues. ALO is designed to avoid storing raw keys in project files.

Contributing

Bug reports, docs fixes, UX feedback, and roadmap ideas are welcome.

License

This project is licensed under the MIT License.

Troubleshooting / Config

Where ALO stores config: Configuration is stored securely using your operating system's standard user configuration directory (e.g., ~/.config/ALO/ALO/config.json on Linux, AppData\Local\ALO\ALO\config.json on Windows).

How to change provider/base URL: Run lo config to update your provider, model, base URL, and key storage preferences. Alternatively, use the interactive dashboard by running lo and navigating to Settings.

How to test API connection: You can test your connection in the TUI (interactive dashboard) by pressing T or selecting "Test API Connection" in the Settings menu.

What to do if settings look wrong: Your config is preserved safely. If a config file becomes invalid, ALO creates a timestamped backup and uses safe defaults. Open Settings in lo and save again to repair. For partial configurations, ALO will explicitly list the missing required fields (like Base URL).

API Keys are not printed: ALO never prints or exposes raw API keys in logs, terminal outputs, or config menus. It will only indicate whether a key is configured correctly in the keyring or environment variables.