{"id":51545155,"url":"https://github.com/marcus/tasks","last_synced_at":"2026-07-09T17:30:57.433Z","repository":{"id":369296663,"uuid":"1286266320","full_name":"marcus/tasks","owner":"marcus","description":null,"archived":false,"fork":false,"pushed_at":"2026-07-04T13:55:06.000Z","size":228,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-04T15:23:10.971Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-07-01T15:50:14.000Z","updated_at":"2026-07-04T13:55:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/marcus/tasks","commit_stats":null,"previous_names":["marcus/tasks"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/marcus/tasks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcus%2Ftasks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcus%2Ftasks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcus%2Ftasks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcus%2Ftasks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcus","download_url":"https://codeload.github.com/marcus/tasks/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcus%2Ftasks/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35308362,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-09T02:00:07.329Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-09T17:30:55.349Z","updated_at":"2026-07-09T17:30:57.422Z","avatar_url":"https://github.com/marcus.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tasks\n\nA plain-text, Claude co-managed task system. The store is a JSONL file that diffs\none task per line. GTD workflow, Covey Important/Urgent matrix. Ruby tooling on top.\n\n## Layout\n\n```\ntasks.jsonl        The one file that matters — you provide this (see below).\nexamples/tasks.jsonl  A tiny sample; copy it to get started.\ndocs/conventions.md  The format + methodology spec (read this).\nbin/tasks          Ruby CLI for querying tasks.jsonl (stdlib only, no gems needed).\nbin/tasks-tui      Interactive TUI: live views, single-key actions, agent prompt.\nlib/tui/           TUI modules (store, views, frame, app loop).\nlib/llm/           LLM agent adapters (Claude CLI, Hermes) behind one protocol.\ntest/              Minitest suite — run with `ruby test/all.rb`.\n```\n\n## Quick start\n\n```sh\ntasks agenda            # (a) what's due / scheduled, soonest first\ntasks next              # (n) next actions grouped by context (@computer, @email, …)\ntasks quadrants         # (q) Covey Important/Urgent 2x2\ntasks inbox             # (i) unprocessed captures\ntasks list              # (l) all tasks grouped by state, with filters (see below)\ntasks capture \"...\"     # (c) append a new item to the Inbox\ntasks done \"...\"        # (d) mark a matching open item DONE\ntasks links             # links in task notes, by system (slack, jira, …)\ntasks open \"...\"        # (o) open a task's link in the browser\ntasks undo              # revert the last mutation (redo mirrors it)\ntasks archive           # (x) sweep DONE/CANCELLED items into archive.jsonl\ntasks -p \"...\"          # hand a request to an LLM agent — it acts and reports back\n```\n\nEvery command has the single-letter alias shown in parentheses (`tasks n`, `tasks x`, …).\n`tasks` itself is aliased to `bin/tasks` in `~/.zshrc`.\n\n## Where your tasks live\n\nYour tasks live in a `tasks.jsonl` (plus `archive.jsonl`) that you own — keep it\nwherever you like; the data is fully separable from the code. Point the tooling\nat it:\n\n```sh\nmkdir -p ~/tasks \u0026\u0026 cp examples/tasks.jsonl ~/tasks/tasks.jsonl   # seed from the sample\nmkdir -p ~/.config/tasks\necho \"dir = ~/tasks\" \u003e ~/.config/tasks/config\ntasks config          # shows the resolved paths and where each came from\n```\n\nIf you set nothing, the tooling falls back to the repo root.\n\nResolution order (both CLI and TUI): `TASKS_FILE`/`TASKS_ARCHIVE` env vars,\nthen `TASKS_DIR`, then the config file (`dir = …`, or per-file `file = …` /\n`archive = …`), then the repo root. Env vars make one-off sandboxes easy:\n`TASKS_FILE=/tmp/scratch.jsonl tasks capture \"test\"`.\n\nThe store is plain text — a JSONL file where each line is one task record, so\nevery change is a one-line, reviewable git diff. The CLI and TUI are the writers;\nit isn't meant for hand-editing (`tasks check` catches any out-of-band edit).\n\n### Filtering with `list`\n\n```sh\ntasks list                     # open items only (default)\ntasks list -d                  # done items still in tasks.jsonl\ntasks list -x                  # archived items\ntasks list -a                  # everything, both files\ntasks list @computer -A /denver  # compose: context, priority, text — all at once\n```\n\nScope flags: `--open/-o` (default) `--done/-d` `--archived/-x` `--all/-a`.\nFilter sigils: `@context`  `/text` (or a bare word)  `+tag`  `-A|-B|-C` (priority).\n\n## Working with an agent\n\nAn LLM agent manages your tasks through the CLI — add captures to the Inbox,\nprocess items into lists, suggest next actions, and surface what matters. The\nplain-text JSONL store means every change is a reviewable, one-line git diff.\n\n**From the terminal**, `tasks -p \"...\"` hands a natural-language request to an\nautonomous agent with `AGENTS.md` as context. It acts on your tasks right where\nyou're working, auto-applies changes, and prints a git diff of the task files\nplus a one-line summary of what it did:\n\n```sh\ntasks -p \"close the Drew review task and push the Denver flight deadline to next Friday\"\ntasks -p --provider hermes \"capture: renew passport\"   # a local Ollama-backed harness\n```\n\nThe agent is a pluggable **harness**: by default the local `claude` CLI, but any\nconfigured backend — e.g. the [Hermes agent](https://hermes-agent.nousresearch.com)\ndriving a local Ollama model — works the same way. Pick the default and add\nmodels in `~/.config/tasks/config`; see `docs/cli-spec.md` (LLM agent settings).\n`AGENTS.md` documents the record format and conventions so any agent stays consistent.\n\n## TUI\n\n`bin/tasks-tui` is a full-screen interactive view over the same file (stdlib only,\nlike everything else). The views update live when `tasks.jsonl` changes — whether you,\nClaude, or another process edited it. The TUI reopens on whichever view you quit\nfrom, with the same subtrees collapsed (session state in\n`$XDG_STATE_HOME/tasks/tui.json`).\n\n```\n1-4 / ←→   switch view: Agenda · Next · Quadrants · Inbox (arrows cycle)\n↑↓ / jk    select a task (also flips tasks inside a detail modal)\nh / l      collapse / expand the selected subtree (h again climbs to the parent)\nH / L      collapse / expand all subtrees\nreturn     task detail modal\n?          keyboard shortcuts modal (/ filters its lines)\n           modals scroll vim-style: j/k line · ctrl-d/u half page · ctrl-f/b page\nc          mark selected task DONE\nd          reschedule — accepts fri, +3, 07-15, 2026-07-15, today, tomorrow\nr          recur — weekly · 2w · .+1m · off\nz / Z      defer (someday/maybe) the selected task / show-hide deferred\nJ / K      lower / raise priority (A ↔ B ↔ C ↔ none)\n/          filter tasks by text (live; enter keeps it, esc clears, / edits)\nu / ctrl-r undo / redo (persistent journal, shared with the CLI's `tasks undo`)\no          open the selected task's link in the browser\ny / Y      yank task ref / full task as markdown to the clipboard\np          paste a quoted task ref into the agent prompt\nx          archive sweep (move DONE/CANCELLED to archive.jsonl)\nM          cycle the agent/model (provider:model shown in the header)\ntab or :   focus the agent prompt — natural-language CRUD on your tasks\nesc        dismiss the response / cancel a running request / close modal\npgup/pgdn  scroll a long response (footer grows, then collapses on esc)\nq          quit\n```\n\nThe agent runs asynchronously (the local `claude` CLI by default, same as\n`tasks -p`, or any configured harness), so the UI stays responsive while it\nworks; its answer appears in an expanding footer pane and the views refresh with\nwhatever it changed. `M` switches backend/model between requests.\n\nColors are themable: `theme = dracula` (or `mono`, `nord`,\n`catppuccin-mocha`, `gruvbox-dark`, `tokyonight-night`, `solarized-dark`, and\nmore) plus per-slot `color.accent = magenta` /\n`color.selection = black on-cyan` lines in `~/.config/tasks/config` restyle\ntabs, the selection bar, modal title strips, task dates, projects, contexts,\ndetail labels, descriptions, links, and more. Popular schemes are generated\nfrom iTerm2-Color-Schemes with `scripts/generate-tui-themes`.\n`NO_COLOR` is honored. See `docs/cli-spec.md` (TUI colors) for the slot and\nspec vocabulary.\n\n## Roadmap / ideas\n\nNear-term:\n\n- Weekly-review helper (empty inbox, flag projects with no NEXT).\n- Optional gem-based version if we outgrow stdlib parsing.\n\nThe full backlog of feature ideas lives in [`docs/ideas.md`](docs/ideas.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcus%2Ftasks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcus%2Ftasks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcus%2Ftasks/lists"}