personal-os

A sanitized, public skeleton of the operating layer I run on top of Claude Code, used every day for study, research, and personal projects.

It is not a framework and not a product. It is the structure: the context files, skills, hooks, and model-routing rules that turn a general coding agent into something that knows my projects and stays cheap to run. This repo is the generic starter. My private instance carries the personal content.

Why this exists

Most people use an AI agent like a chatbot. The leverage is one layer down: writing the skills, wiring the CLIs and MCP servers, and giving the agent a context architecture it can actually navigate. That authoring work is the real skill, and it never shows up in a chat transcript. So I am putting the structure here, where you can read it.

Honest caveat: being good at this is a head start, not a moat. Eventually everyone learns these tools. I am using the head start to buy time for the ML depth underneath (the math, the papers, the eval work on my profile). This repo is the "now" half of that bet.

What's inside

Path	What it is
AGENTS.md	The context layer. How the agent gets project context without re-reading everything.
skills/	Reusable, single-purpose workflows the agent can invoke. This is the "know how to write skills" part.
hooks/	Deterministic automations that fire around tool calls. The harness runs these, not the model.
docs/architecture.md	The multi-layer context system, end to end.
docs/token-economy.md	Model routing and cost control. The boring part that makes daily use sustainable.

Architecture at a glance

You ──▶ Claude Code (the agent)
            │
   ┌────────┼───────────────────────────────┐
   │        │                                │
 context   skills                          hooks
 layer     (invokable workflows)           (deterministic, around tool calls)
   │        │                                │
   ▼        ▼                                ▼
 AGENTS.md  SKILL.md + scripts             pre / post tool-use scripts
 memory     one job per skill              prompt nudges
 project                                   the harness executes these
 HUBs
            │
            ▼
   tools: CLIs first, MCP servers as fallback

Full walkthrough in docs/architecture.md.

Status

v0.1 skeleton, work in progress, built in public. The examples are generic on purpose. The patterns are the point, not my private content.

Who made this

Orazio Oztas, MSc Computational Linguistics @ University of Turin. Heading to UCLouvain for an exchange in September 2026, learning the ML underneath in public.

• Email: orazio.oztas@gmail.com
• LinkedIn: https://www.linkedin.com/in/orazio-oztas-a48848232/
• X: https://x.com/OrazioOzta76081
• GitHub: https://github.com/oraziooztas

License: MIT.