1 line
13 KiB
JSON
1 line
13 KiB
JSON
{"repo": "av-feaster/habitos", "files": {"README.md": {"ac532ee3c5b3bf756ad3e2a6fbf2c4183c3e2918": {"t": 1785674412.6042225, "n": 12223, "h": "de09e5d38cf503da", "c": "# HabitOS\n\n> A local-first, AI-optional terminal OS for running your life — habits, goals, focus, journal, reflection, and long-term memory in one immersive CLI.\n\n[](https://asciinema.org/a/yXRwfVD2KTqNLdqI?autoplay=1)\n\nHabitOS lives where developers already are: the terminal. Everything is one binary, one SQLite file, and zero cloud calls. AI is opt-in — every feature has a deterministic fallback that works offline.\n\n> **This is v0.1.** I'm shipping early on purpose to find out what's broken before committing more time. If you try it and it doesn't stick, [tell me why](https://github.com/av-feaster/habitos/issues/new?template=feedback.yml) — \"I bounced because X\" is the most valuable thing I can hear right now.\n\n---\n\n## Why HabitOS\n\nMost personal-execution tools fall into one of two camps:\n\n- **Web/mobile apps** (Notion, Todoist, Streaks): great UX, but data lives in someone else's cloud and you context-switch out of your editor to use them.\n- **CLI tools** (jrnl, habitctl, taskwarrior): local-first, but each does one thing — you end up gluing five of them together.\n\nHabitOS is the missing combination: **terminal-first, local-first, single-binary, AI-augmented when you want it**.\n\n- **🔒 Local-first** — SQLite database in `~/Library/Application Support/habitos/`. Your data never leaves your machine.\n- **⚡ Fast** — `<10ms` startup. The TUI redraws at 60fps.\n- **🧠 AI-optional** — Configure Claude, Ollama, or any OpenAI-compatible backend in 1 line. Or don't, and use the deterministic mode.\n- **🎯 Sticky core** — Habit streaks, focus timer, and friction-free journaling are the things you actually use daily. Everything else supports those.\n- **📦 One binary** — `cargo install habitos` and you're done.\n\n---\n\n## Install\n\n### Homebrew (macOS Apple Silicon / Intel, Linux x86_64)\n\n```bash\nbrew install av-feaster/tap/habitos\nhabitos --version\n```\n\n### From source (any platform with Rust ≥ 1.85)\n\n```bash\ngit clone git@github.com:av-feaster/habitos.git\ncd habitos\ncargo install --path habitos-cli\nhabitos --version\n```\n\nIf `habitos` isn't found after a cargo install, ensure `~/.cargo/bin` is on your `PATH`:\n\n```bash\necho '. \"$HOME/.cargo/env\"' >> ~/.zshrc\nsource ~/.zshrc\n```\n\n### Pre-built binaries\n\nTarballs for each platform are attached to every [GitHub Release](https://github.com/av-feaster/habitos/releases). Download, extract, and drop `habitos` into a directory on your `PATH`.\n\n---\n\n## Quick start\n\n```bash\nhabitos init # 30-second interactive setup\n```\n\nThat walks you through creating a habit, logging it, and optionally connecting an AI backend. Or skip the wizard:\n\n```bash\nhabitos habit add DSA\nhabitos habit add Workout\n\n# Log today in one line — infers habit, duration, and saves a journal note\nhabitos log \"did DSA for 45min\"\n# ✓ DSA done, 45m focus, journal +1\n# 🌱 7-day streak on DSA — keep going.\n\n# Launch the immersive dashboard\nhabitos\n```\n\nThat's it. Add the alias `alias l='habitos log'` and your daily flow is `l \"...\"`.\n\n---\n\n## Core commands\n\n| Command | What it does |\n|---|---|\n| `habitos` | Open the immersive TUI dashboard |\n| `habitos init` | Interactive first-run setup |\n| `habitos log \"did X for Nmin\"` | One-line capture: habit + focus + journal in one shot |\n| `habitos habit add <name>` | Create a habit |\n| `habitos habit done <name>` | Mark done today |\n| `habitos habit stats` | Streaks, completion rate, freezes used |\n| `habitos goal add <name>` | Create a goal |\n| `habitos goal milestone add <goal> <name>` | Add a milestone |\n| `habitos focus start --project X` | Start a focus session |\n| `habitos focus stop` | End the session, record duration |\n| `habitos journal new` | Open `$EDITOR` for today's entry |\n| `habitos reflect` | Guided 4-question end-of-day reflection |\n| `habitos review day\\|week\\|month` | Templated report from raw data |\n| `habitos insights` | Quantitative patterns (most-active hour, stale goals, …) |\n| `habitos heatmap` | GitHub-contributions-style year heatmap |\n| `habitos nudge` | Smart, loss-aversion-framed pending reminder |\n| `habitos ask \"<question>\"` | Semantic search over your journal (AI required) |\n| `habitos plan` | AI-generated daily plan (Claude / Ollama) |\n| `habitos coach` | AI coach: patterns, recommendation, next step |\n| `habitos export markdown` | Single markdown doc to stdout |\n| `habitos export csv <dir>` | One CSV per entity |\n\n---\n\n## The TUI\n\n`habitos` (no args) opens a live two-column dashboard:\n\n- **Left** — today's habits with streak counters (🔥 emoji from 3+ days, color-graded by length) and active focus session with live ticker\n- **Right** — open goals with progress bars and today's journal preview\n- **Header** — a 0–100 daily score (50% habits done + 30% focus hours capped at 4h + 10% journal + 10% reflection)\n- **Footer** — keybinding hints\n\n### Keybindings\n\n| Key | Action |\n|---|---|\n| `↑` `↓` / `j` `k` | Move cursor through habits |\n| `d` | Mark habit done |\n| `s` | Mark habit skipped |\n| `f` | Start / stop focus session |\n| `e` | Open today's journal in `$EDITOR` (TUI suspends, resumes after save) |\n| `r` | Refresh |\n| `?` | Help overlay |\n| `q` / `^C` | Quit |\n\n### Themes\n\n```bash\nhabitos --theme system # default — uses your terminal's ANSI palette\nhabitos --theme vivid # true-color cyan/green/amber\nhabitos --theme mono # no color, only bold/dim\n```\n\n---\n\n## AI integration\n\nHabitOS supports three backends. Configure with one command:\n\n```bash\n# Anthropic Claude\nhabitos connect claude sk-ant-...\n\n# Local Ollama (auto-pulls the model)\nhabitos connect ollama gemma2:2b\nhabitos connect ollama qwen2.5:3b\nhabitos connect ollama llama3.2:3b\n\n# Shortcuts\nhabitos connect gemma # default: gemma2:2b\nhabitos connect qwen # default: qwen2.5:3b\n\n# Inspect / clear\nhabitos connect status\nhabitos connect off\n```\n\nAfter connecting:\n\n```bash\nhabitos ai check # 1-token probe\nhabitos plan # AI-generated plan\nhabitos coach # AI coaching\nhabitos ask \"what was I focused on in May?\"\n```\n\nIf no backend is configured, every command falls back to a deterministic version. `plan` prints raw context. `coach` shows the same. `ask` returns a clear error (needs embeddings).\n\n**Note:** Anthropic's API doesn't provide embeddings, so `ask` requires Ollama. The other AI commands work fine on Claude.\n\n---\n\n## The engagement layer\n\nA few features designed for daily stickiness:\n\n### Streak freeze (1 per ISO week)\nA single missed day per week is forgiven — no all-or-nothing cliff. The `❄` indicator in `habitos habit stats` shows when a freeze was consumed.\n\n### Auto-detected milestones\nAt 7 / 30 / 60 / 100 / 365 day streaks, the next log triggers a celebration:\n\n```\n✓ DSA done, journal +1\n🌱 7-day streak on DSA — keep going.\n```\n\n### Smart 9pm nudge (macOS)\nA launchd job runs `habitos nudge --notify` at 21:00. Instead of a generic \"log your habits\", it picks the most at-risk streak:\n\n> Workout pending — your 5-day streak ends if you skip today.\n\n### Year heatmap\n\n```bash\n$ habitos heatmap\n Jul Aug Sep Oct Nov Dec Jan Feb Mar Apr May Jun\n Mon ░▒▓▓██▓▒░░░▒▒▓▓███▓▓▒░░▒▒▓████▓▓▒▒▒▓▓██▓▓▒▒░░▒▓██▒░░▒▓██▓▒░▓█▓░\n Tue ▒▒▓▓██▓▒░▒▒▓▓███▓▓▒░░▒▒▓████▓▓▒▒▒▓▓██▓▓▒▒░░▒▓██▒░░▒▓██▓▒░▓█▓░░▒\n ...\n less ░ ▒ ▓ █ more\n```\n\n### Terminal nudge on shell open\n\nAdd to `~/.zshrc`:\n\n```bash\nHABITOS_NUDGE_FILE=\"$HOME/.habitos_nudge\"\nhabitos-nudge() { case \"$1\" in on|off) echo \"$1\" > \"$HABITOS_NUDGE_FILE\";; *) cat \"$HABITOS_NUDGE_FILE\" 2>/dev/null || echo on;; esac }\nif [ -z \"$HABITOS_NUDGED\" ] && [ \"$(cat \"$HABITOS_NUDGE_FILE\" 2>/dev/null || echo on)\" = \"on\" ] && command -v habitos >/dev/null; then\n export HABITOS_NUDGED=1\n habitos habit stats\nfi\n```\n\nEvery new shell shows your streaks at a glance.\n\n---\n\n## Architecture\n\nA 3-crate Rust workspace:\n\n```\nhabitos-cli/ Binary. clap subcommand tree + ratatui TUI.\nhabitos-core/ Domain types, sqlx persistence, pure-function business logic.\n ├── habits, goals, focus, journal, reviews\n ├── capture (one-line parser)\n ├── heatmap, milestones, reports\n ├── memory (embedding store + cosine retrieval)\n └── events (audit log)\nhabitos-ai/ LlmClient trait + Ollama, OpenAI-compatible, Anthropic impls.\n Prompts loaded from disk (overridable) or embedded defaults.\n```\n\n**Conventions:**\n\n- All timestamps stored as ISO-8601 UTC. Calendar dates (habit logs, journal entries) stored as the user's local day — a reflection logged at 2am still counts for the day it felt like.\n- `thiserror` in libraries, `anyhow` at the CLI boundary. No `unwrap()` outside tests.\n- Migrations are forward-only.\n- The `LlmClient` trait is depended on by every AI call site; concrete clients are constructed via `build_client(&AiBackendConfig)` so adding a new backend is one match arm.\n- Embeddings stored as raw `f32` bytes in SQLite BLOB (cosine sim in Rust). At V1 scale this is faster than loading a vector extension. The retrieval function is the only swap point if you need `sqlite-vec`.\n\n---\n\n## Configuration\n\nConfig lives at `~/Library/Application Support/habitos/config.toml`. Show paths with:\n\n```bash\nhabitos config path\n```\n\nExample:\n\n```toml\n[ai]\nbackend = \"anthropic\" # \"ollama\" | \"openai-compatible\" | \"anthropic\"\nmodel = \"claude-sonnet-4-6\"\nendpoint = \"https://api.anthropic.com\"\napi_key = \"sk-ant-...\"\ntimeout_secs = 30\n```\n\nOverride the data directory with `HABITOS_HOME=/path` (useful for testing).\n\n### Sync across machines (without code)\n\nHabitOS is single-file SQLite. To use it across a laptop + desktop, point the data dir at a synced folder:\n\n```bash\n# iCloud Drive (macOS)\nexport HABITOS_HOME=\"$HOME/Library/Mobile Documents/com~apple~CloudDocs/habitos\"\n\n# Dropbox\nexport HABITOS_HOME=\"$HOME/Dropbox/habitos\"\n\n# Syncthing or any directory under it\nexport HABITOS_HOME=\"$HOME/Sync/habitos\"\n```\n\nAdd the export to `~/.zshrc` for persistence. SQLite handles concurrent reads cleanly; single-user writes won't collide as long as you're not running `habitos` on two machines at the exact same instant.\n\n### Prompt overrides\n\nAI prompts ship as embedded defaults but can be overridden without recompiling — drop a file into `~/Library/Application Support/habitos/prompts/`:\n\n```\nprompts/plan.md\nprompts/coach.md\nprompts/reflect_summary.md\nprompts/review_week.md\nprompts/ask.md\n```\n\n---\n\n## A daily workflow that actually works\n\nAfter using it for a while, this is the loop that sticks:\n\n```bash\n# Morning\nhabitos # see streaks + score; plan the day\nhabitos plan # if AI is on, get a Claude-generated agenda\n\n# During the day\nl \"did DSA 45min\" # one-line capture, repeat as you go\nhabitos focus start --project hostops\n# … deep work …\nhabitos focus stop\n\n# Evening\nhabitos reflect # 4 prompts, two minutes\nhabitos review day # see the whole day at once\n```\n\n**Recommended:** track **2–3 habits max**. People who track ten habits stop tracking entirely.\n\n---\n\n## Roadmap\n\nShipped (V1):\n\n- ✅ Habit / goal / focus / journal / review primitives\n- ✅ Deterministic reports + insights\n- ✅ AI integration (Claude / Ollama / OpenAI-compatible)\n- ✅ Long-term memory + `ask`\n- ✅ Export (markdown + CSV)\n- ✅ Immersive ratatui TUI\n- ✅ One-line capture (`log`)\n- ✅ Smart nudge + auto-detected milestones\n- ✅ Heatmap + streak freezes + daily score\n\nIn flight (V1.1):\n\n- ⏳ Inline add-habit form in TUI\n- ⏳ Split AI config: Claude for completions + Ollama for embeddings\n- ⏳ Prompt caching for Anthropic\n- ⏳ Goal-mutation `event_log` writes\n- ⏳ Pomodoro structure on focus sessions\n\nConsidered (V2+):\n\n- TUI tabs for goals/reviews/insights\n- Live AI streaming inside the TUI\n- Mobile companion + multi-device sync\n- Plugin system (Obsidian, Calendar, Telegram)\n\n---\n\n## Tests\n\n```bash\ncargo test --workspace # 37 unit tests\ncargo clippy --workspace -- -D warnings\ncargo fmt --all --check\n```\n\nCoverage focuses on the pure-function layers: streak math, capture parser, heatmap intensity, milestone thresholds, cosine + top-k retrieval, config round-trip. Persistence is exercised via an in-memory SQLite migration test.\n\n---\n\n## License\n\nMIT.\n"}}}} |