{"id":49597069,"url":"https://github.com/erans/mostly","last_synced_at":"2026-05-04T05:05:59.480Z","repository":{"id":349706114,"uuid":"1202522014","full_name":"erans/mostly","owner":"erans","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-28T00:06:27.000Z","size":735,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-28T02:19:55.185Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/erans.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":null,"dco":null,"cla":null}},"created_at":"2026-04-06T05:33:21.000Z","updated_at":"2026-04-28T00:06:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/erans/mostly","commit_stats":null,"previous_names":["erans/mostly"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/erans/mostly","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erans%2Fmostly","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erans%2Fmostly/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erans%2Fmostly/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erans%2Fmostly/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/erans","download_url":"https://codeload.github.com/erans/mostly/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erans%2Fmostly/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32595266,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T22:12:39.696Z","status":"online","status_checked_at":"2026-05-04T02:00:06.625Z","response_time":58,"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-05-04T05:05:58.727Z","updated_at":"2026-05-04T05:05:59.463Z","avatar_url":"https://github.com/erans.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mostly\n\nA local-first, agent-friendly task tracker. SQLite-backed, designed for AI agents and humans to collaborate on task management through CLI, HTTP API, or MCP.\n\n## Architecture\n\nMostly is a pnpm monorepo with seven packages:\n\n| Package | Description |\n|---------|-------------|\n| `@mostly/types` | Shared types, Zod schemas, enums, and error classes |\n| `@mostly/core` | Domain logic: state machine, services, claim system |\n| `@mostly/db` | SQLite storage via Drizzle ORM, repositories, migrations |\n| `@mostly/server` | HTTP API server (Hono) |\n| `@mostly/cli` | Command-line interface (Commander.js) |\n| `@mostly/mcp` | MCP server for AI agent integration |\n| `@mostly/web` | Web frontend (React + Vite SPA) |\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js 20+\n- pnpm 9+\n\n### Install and Build\n\n```bash\npnpm install\npnpm build\n```\n\n### Initialize\n\n```bash\nmostly init\n```\n\nThis prompts for an admin handle and password, creates the database, seeds the default workspace, and generates a one-time workspace **agent token** (used by agents and CI — shown once, then SHA-256 hashed in the database). The admin password is stored as a bcrypt hash. The resulting `~/.mostly/config` holds the server URL, the agent token, and `default_actor` pointing at the admin handle.\n\n### Start the Server\n\n```bash\nmostly serve\n```\n\nThe server runs at `http://localhost:6080` by default.\n\n### Sign In\n\nThe admin account from `init` is a real user — sign in to create a per-user API key:\n\n```bash\nmostly login\n```\n\nThis prompts for your handle and password, then stores an API key named `cli-\u003chostname\u003e` in `~/.mostly/config` under `api_key`. Subsequent CLI commands use the API key automatically (the server resolves your identity from it, so no `--actor` flag is needed).\n\nIf you skip `mostly login` and rely on the agent token that `init` wrote, commands still work — `init` also persists `default_actor` pointing at the admin handle, so the CLI knows which principal to act as. Pass `--actor \u003chandle\u003e` on an individual command when you need to override that default (e.g. to act as a different agent for one invocation).\n\n### Basic Usage\n\n```bash\n# Create an agent principal. Agents authenticate via the shared workspace\n# agent token and identify themselves via `actor_handle` on mutations\n# (persisted by `init` as `default_actor`). Humans should use\n# `mostly invite` instead so they get their own password and API keys.\nmostly principal create --handle build-bot --kind agent\n\n# Create a project\nmostly project create --key AUTH --name \"Authentication\"\n\n# Create a task\nmostly task create --title \"Add login page\" --type feature --project AUTH\n\n# List tasks\nmostly task list\n\n# Claim a task for exclusive work\nmostly task claim AUTH-1 --ttl 2h\n\n# Transition a task\nmostly task start AUTH-1\nmostly task close AUTH-1 --resolution completed\n```\n\n### Git-aware project inference\n\nWhen `mostly` commands run inside a git repository that has been linked to a project, they fill in `--project`, `--task`, and `--actor` automatically. Pass `--no-git-context` on any command to skip inference for that invocation.\n\n**Linking a repo to a project**\n\n```bash\ncd path/to/your/repo\n\nmostly project link --project AUTH               # link origin to project AUTH\nmostly project link --project AUTH --all-remotes # link every remote on the repo\nmostly project link --project AUTH --subpath packages/auth  # monorepo subpath\n\nmostly project links                             # list all workspace links\nmostly project unlink --project AUTH             # remove the origin link\n```\n\nA single repo can have multiple links — one per remote or subpath. For monorepos, the longest matching subpath wins when the CLI resolves the active project.\n\n**Branch → task inference**\n\nThe CLI parses the current branch for a pattern matching the linked project key. Any of these resolve to task `AUTH-1`:\n\n- `AUTH-1-add-login` — key prefix\n- `feature/AUTH-1` — slash-separated segment\n- `eran/AUTH-1-foo` — personal namespace\n\nThe project key in the branch must match the linked project exactly (case-sensitive). Branches that contain a different project key are ignored — they will not cause the CLI to switch projects.\n\n**Actor inference from email**\n\n`git config user.email` is matched against principal emails in the workspace. Inactive principals are skipped. If exactly one active principal matches, that handle is used as the actor. If multiple principals share the same email, inference falls back to `default_actor` from `~/.mostly/config`.\n\nRun `mostly login` once to set your email on your principal so inference works for you.\n\n**`mostly whereami` — inference diagnostic**\n\n```\n$ mostly whereami\ncwd:        /home/eran/work/auth\nrepo:       /home/eran/work/auth\nbranch:     AUTH-1-add-login\nemail:      eran@example.com\nremotes:\n  origin: github.com/acme/auth\ninferred:\n  project: AUTH (git:resolve)\n  task:    AUTH-1 (git:branch)\n  actor:   eran (git:email)\n```\n\n`whereami` is read-only and makes no changes.\n\n### MCP Integration\n\nRun the MCP server for AI agent access:\n\n```bash\nmostly-mcp\n```\n\nThis exposes all task operations as MCP tools over stdio, compatible with Claude and other MCP-enabled AI agents.\n\n### Web Frontend\n\nStart the web UI for a browser-based task management interface:\n\n```bash\ncd packages/web \u0026\u0026 pnpm dev\n```\n\nThe web UI runs at `http://localhost:5173` and connects to the Mostly server at `http://localhost:6080`. On first load, enter the server URL, then sign in with your admin credentials (or register the first user if the database is empty). The session is held in an `httpOnly` cookie. Features include a three-panel layout (sidebar, task list, detail panel), command palette (Cmd+K), task creation, status transitions, claims, an API Keys settings page, and light/dark themes.\n\n## Authentication\n\nMostly supports three authentication methods, which the server's auth middleware tries in order:\n\n| Method | Used by | How it's obtained |\n|--------|---------|-------------------|\n| **Session cookie** | Web frontend | `POST /v0/auth/login` sets an `httpOnly`, `SameSite=Lax` cookie with 7-day sliding expiry |\n| **Personal API key** (`msk_*`) | CLI, HTTP clients | `mostly login` stores one in `~/.mostly/config`; additional keys via `mostly api-key create \u003cname\u003e` |\n| **Agent token** (`mat_*`) | Agents, MCP server, CI | Generated by `mostly init`, shared across all agents in a workspace, paired with an `actor_handle` on each mutating request so the server knows which agent is acting |\n\nHumans authenticated by session or API key have their identity resolved server-side — the `actor_handle`/`actor_id` fields in request bodies are ignored. Agents authenticated by the shared token must include `actor_handle` on mutating requests (the CLI's `default_actor` config field and `--actor` flag, and the MCP server's `MOSTLY_ACTOR` env var, do this automatically). GET requests under agent-token auth do not require an actor.\n\n### First-user registration\n\n`POST /v0/auth/register` is open when no human principals exist yet — the first caller becomes the admin. After that, registration is invite-only unless the workspace has `allow_registration=true`. Use `mostly invite \u003chandle\u003e` or the admin web UI to issue an invite token; the invitee sets their password via the accept-invite flow.\n\n### Admin tasks\n\n- `mostly invite \u003chandle\u003e` — create a one-time invite link for a new user (admin only)\n- `mostly principal reset-password \u003chandle\u003e` — admin-only password reset (invalidates existing sessions for that user)\n- `mostly api-key list` / `mostly api-key revoke \u003cname\u003e` — manage your own keys\n\n## Key Concepts\n\n### Claims\n\nTasks support exclusive claims with optional TTL expiry. When an agent claims a task, other agents know the task is being actively worked on. Claims can be renewed or released, and expired claims are automatically reaped.\n\n### State Machine\n\nTasks follow a defined lifecycle: `open` -\u003e `claimed` -\u003e `in_progress` -\u003e `blocked` -\u003e `closed`/`canceled`. Transitions are validated with appropriate side effects (claim release on close, resolution tracking on terminal states).\n\n### Optimistic Concurrency\n\nAll mutations require an `expected_version` parameter. If the task was modified since you last read it, the operation fails with a conflict error rather than silently overwriting changes.\n\n### Workspace Scoping\n\nAll entities are scoped to a workspace, preventing cross-tenant data access.\n\n## API\n\nThe HTTP API is available at `/v0/` with endpoints for:\n\n- `GET/POST /v0/principals` - Manage users and agents\n- `GET/POST /v0/projects` - Manage projects\n- `GET/POST /v0/tasks` - CRUD operations on tasks\n- `POST /v0/tasks/:id/transition` - Status transitions\n- `POST /v0/tasks/:id/claim` - Claim management\n- `GET/POST /v0/tasks/:id/updates` - Task updates and notes\n\nAll endpoints require authentication. See [Authentication](#authentication) for the three supported methods (session cookie, personal API key, shared agent token).\n\n## Development\n\n```bash\n# Run all tests\npnpm test\n\n# Run end-to-end tests\npnpm test:e2e\n\n# Build all packages\npnpm build\n```\n\n## Deploying to Cloudflare\n\nFor a fresh install or to push updates, run:\n\n    ./scripts/deploy-cloudflare.sh init      # first time\n    ./scripts/deploy-cloudflare.sh update    # subsequent deploys\n\nSee [`docs/cloudflare-deployment.md`](docs/cloudflare-deployment.md) for\ndetails, custom domain setup, and manual provisioning instructions.\n\n## License\n\nApache License 2.0 - see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferans%2Fmostly","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ferans%2Fmostly","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferans%2Fmostly/lists"}