PersonalOS: A Markdown Backlog That an AI Assistant Turns Into Prioritized Tasks
Framework for a local AI agent powered task management system
At a glance
- What is it?
- PersonalOS is a bash-installed framework that keeps your tasks in plain Markdown files and delegates prioritization to an AI assistant reading your GOALS.md. The design is deliberately thin on software and heavy on prompt instructions, which is both its appeal and its main constraint.
- Who is it for?
- Adopt PersonalOS if you already work inside an AI assistant that can read local files and you want your task list to stay as plain Markdown you can edit by hand. Do not adopt it if you need a scheduler, notifications, or any behavior that runs without an assistant in the loop, and do not adopt it for a commercial product, because the CC BY-NC-SA 4.0 terms bar commercial sale.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 177 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Problem: A Backlog File Nobody Processes
Most personal task systems fail at the same point. Capturing a thought is easy, and deciding what it is worth relative to everything else is not. PersonalOS targets that second step. The README describes the loop plainly: you drop unstructured notes into BACKLOG.md, tell your assistant to process the backlog, and the assistant creates prioritized tasks based on your GOALS.md. There is no database, no web interface, and no background service. The repository is a directory layout plus a set of instruction files.
The audience is narrow and identifiable. It is for one person, working on one machine, who already talks to an AI assistant that can read and write files in a project folder. The README's own example is Claude Code, and the MCP server is described as optional. If your assistant cannot open AGENTS.md and edit files under Tasks/, the framework has nothing to drive it. Anyone expecting a standalone application with a login screen will find a folder of Markdown instead.
How the Loop Actually Runs
The mechanism is a file convention rather than a program. setup.sh creates workspace directories, asks questions about your goals and priorities, generates a personalized GOALS.md, and copies template files into place. From then on, the assistant reads AGENTS.md as its operating instructions, reads GOALS.md as the ranking criteria, reads BACKLOG.md as raw input, and writes structured task files into Tasks/.
The priority scheme is fixed in the README as a four-level table: P0 means do today with a maximum of three items, P1 means this week with a maximum of seven, P2 is scheduled with no stated cap, and P3 is someday or maybe. Those caps are the most interesting design decision in the project. A maximum of three P0 tasks is a hard constraint on what the assistant is allowed to call urgent, and it forces the ranking to produce an ordering rather than a pile. The cost is that the assistant must demote something when a fourth item genuinely is urgent, and the README does not describe what happens then.
Deduplication is handled inside core/mcp/server.py, which the directory listing annotates as the core server with deduplication. The README lists smart deduplication as a feature that detects duplicate tasks, but it does not explain the matching rule. Whether that is exact string comparison, fuzzy matching, or something the model decides is not stated anywhere in the supplied material.
Setup Commands and the Python Boundary
Installation is three steps. Clone the repository, run the setup script, then address your assistant:
git clone https://github.com/amanaiproduct/personal-os.git cd personal-os ./setup.sh
The README states the setup takes about two minutes and that Python 3.10 or newer is only needed if you want to run the MCP server. Basic use works with bash alone. That split matters: the everyday workflow is file editing and natural language, while Python is reserved for the optional MCP path that exposes the system to assistants through the Model Context Protocol.
The interaction surface is a small vocabulary of phrases rather than commands. The README lists "Process my backlog", "What should I work on?", "Show me my P0 tasks", and "Mark [task] as done". There is also a config.yaml template under core/templates/, though the README does not document its keys, so anyone wanting to change behavior beyond editing GOALS.md and AGENTS.md has to read the template itself. The suggested cadence is daily capture with an end-of-day completion step, plus a weekly pass that combines processing the backlog with cleaning up old tasks.
What Stays Out of Git
The directory structure separates the reusable system from personal content. core/ holds evals, the MCP server, and templates including AGENTS.md, config.yaml, and a gitignore template. Tasks/, Knowledge/, BACKLOG.md, and GOALS.md are marked gitignored. That split is what makes the repository forkable: the contributor guidance asks that contributions not include personal information, stay generic and configurable, include documentation, and follow existing patterns.
There is a practical consequence worth noting. Because Tasks/ and BACKLOG.md are ignored by default, the system has no built-in sync or history. Your task state lives on one disk, and recovery depends on whatever backup you run outside the project. The README does not mention backup, export, or migration. For a system whose entire value is the accumulated contents of Tasks/ and GOALS.md, that is a real gap rather than a missing convenience.
Where the Framework Stops
PersonalOS is instructions plus directory scaffolding. It does not schedule, remind, notify, or run on its own. Nothing in the README suggests a daemon, a cron entry, or a mobile client. If you stop opening your assistant, the backlog stops being processed, and the P0 cap of three has no enforcement mechanism beyond the assistant following AGENTS.md.
That leads to the failure mode that matters most. The quality of prioritization is the quality of GOALS.md and of the model reading it. A vague goals file produces vague rankings, and the README's own setup step is the only place where goals get captured. The session evals feature under core/evals/ is presented as a way to review and learn from AI interactions, which suggests the project expects you to inspect and correct the assistant's output rather than trust it. There is no stated accuracy claim, no benchmark, and no test suite described in the material, so the reliability of deduplication and prioritization is unverified here.
The wrong-tool case is a team. A shared backlog with multiple contributors, assignment, and status transitions needs a server and a permission model. PersonalOS is single-user by construction, and the gitignored task directory means there is no shared state to coordinate on.
Compared With Plain Obsidian and Todoist
The closest alternative is a Markdown vault in an editor like Obsidian, optionally with a tasks plugin. Both approaches store tasks as text files you own. The difference is where prioritization lives. In a vault, ordering comes from tags, due dates, and whatever query syntax the plugin supports, and it is deterministic: the same query returns the same list every time. In PersonalOS, ordering comes from a language model reading GOALS.md, so the output can change between runs and depends on how the goals are phrased. Determinism is traded for judgment.
Against a hosted tool like Todoist, the split is different again. Todoist runs its own sync, reminders, and mobile apps, and it works whether or not you have an AI assistant installed. PersonalOS has none of that infrastructure and instead assumes the assistant is already your primary interface. The honest framing is that PersonalOS is not competing on features. It competes on keeping the task list inside the same files and the same conversation window you already use for work.
Licence and Maintenance Reality
The repository badge and the licence section both point to CC BY-NC-SA 4.0, with copyright held by Aman Khan. The README states you may view, use, modify, and share the work with attribution for non-commercial purposes, that commercial sale is not permitted, and that internal use at work and in business is allowed. That last clause is the one people misread. Using it inside a company appears permitted; selling a product built on it does not. ShareAlike also means derivative distributions carry the same licence. This is a summary of what the README says, not legal advice, and the metadata for the repository lists the licence as NOASSERTION, so anyone planning to redistribute should read the linked legal code rather than the badge.
On maintenance, the supplied material shows a last push on 2026-03-22 and no retrieved releases. There is no changelog, no versioning scheme, and no upgrade path described. Because the live parts of the system are Markdown files you own and a bash script you ran once, an upstream change to AGENTS.md or the templates does not automatically reach your copy. Pulling updates means diffing your personalized AGENTS.md and GOALS.md against the templates by hand, and the README offers no procedure for that. Budget for it as a manual merge, not an upgrade command.
Editorial conclusion
Adopt PersonalOS if you already work inside an AI assistant that can read local files and you want your task list to stay as plain Markdown you can edit by hand. Do not adopt it if you need a scheduler, notifications, or any behavior that runs without an assistant in the loop, and do not adopt it for a commercial product, because the CC BY-NC-SA 4.0 terms bar commercial sale. Verify first that your chosen assistant can actually read AGENTS.md and write into Tasks/, since the repository supplies instructions rather than an executable task engine.
Community notes