{"id":30182713,"url":"https://github.com/tesso57/locus","last_synced_at":"2025-08-12T10:15:51.824Z","repository":{"id":304469428,"uuid":"1014874687","full_name":"tesso57/locus","owner":"tesso57","description":"Locus is a Git-aware, local-first task management CLI, designed to streamline your development workflow, especially when working with AI coding assistants.","archived":false,"fork":false,"pushed_at":"2025-07-24T11:20:04.000Z","size":237,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-08T23:15:29.998Z","etag":null,"topics":["cli","jsr","npm"],"latest_commit_sha":null,"homepage":"https://jsr.io/@tesso/locus","language":"TypeScript","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/tesso57.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/funding.yml","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},"funding":{"github":["tesso57"]}},"created_at":"2025-07-06T15:23:05.000Z","updated_at":"2025-07-30T04:18:04.000Z","dependencies_parsed_at":"2025-07-24T09:04:02.823Z","dependency_job_id":null,"html_url":"https://github.com/tesso57/locus","commit_stats":null,"previous_names":["tesso57/locus"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tesso57/locus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tesso57%2Flocus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tesso57%2Flocus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tesso57%2Flocus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tesso57%2Flocus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tesso57","download_url":"https://codeload.github.com/tesso57/locus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tesso57%2Flocus/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270041725,"owners_count":24516913,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-12T02:00:09.011Z","response_time":80,"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":["cli","jsr","npm"],"created_at":"2025-08-12T10:15:50.699Z","updated_at":"2025-08-12T10:15:51.812Z","avatar_url":"https://github.com/tesso57.png","language":"TypeScript","funding_links":["https://github.com/sponsors/tesso57"],"categories":["\u003ca name=\"programming\"\u003e\u003c/a\u003eProgramming"],"sub_categories":[],"readme":"# Locus\n\n[![Version](https://img.shields.io/badge/version-0.1.9-blue.svg)](https://github.com/tesso57/locus)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![CI](https://github.com/tesso57/locus/actions/workflows/ci.yml/badge.svg)](https://github.com/tesso57/locus/actions/workflows/ci.yml)\n[![Deno](https://img.shields.io/badge/Deno-2.x-000000?logo=deno)](https://deno.com)\n[![JSR](https://jsr.io/badges/@tesso/locus)](https://jsr.io/@tesso/locus)\n[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)](https://github.com/tesso57/locus)\n\n_Locus_ is a Git-aware, local-first task management CLI, designed to streamline your development workflow, especially when working with **AI coding assistants**.\n\nBorn from extensive collaboration with AI coding assistants, Locus solves a fundamental problem: to get high-quality work from an agent, you need well-structured Markdown briefs for every task. And when running multiple agents in parallel, you need a fast, local way to manage those files. While GitHub Issues is conceptually close, it lives in the cloud and is awkward to drive from a CLI that an agent can call.\n\nLocus is the solution: a Git-native, local-first CLI task manager where each task lives in its own Markdown file that an AI assistant can read and write. Think of it as a **simple, local version of GitHub Issues** that helps you break down complex work into small, manageable pieces, enabling agents to work more autonomously and produce higher-quality results for tasks like large-scale refactoring or test generation.\n\nOf course, it's also a great tool for managing your own daily tasks without cluttering up your official project boards.\n\n[日本語版 README](docs/README_ja.md)\n\n## Usecase\n\n\u003cdetails\u003e\n\u003csummary\u003eAI-Assisted Development Workflow\u003c/summary\u003e\n\n_Locus_ is useful for AI-assisted development workflows. By breaking down complex work into a series of well-defined tasks, you can more effectively guide an AI to perform large-scale or repetitive work.\n\nHere's a common workflow for generating test files using _Locus_ and an AI assistant:\n\n### 1. Create a Task Template\n\nFirst, create a generic template for the task. This template can include placeholders like `$FILE_NAME`.\n\n**`test_template.md`**:\n\n```markdown\n# Create tests for $FILE_NAME\n\n- [ ] Read `docs/testing.md` to understand our testing strategy.\n- [ ] Scan the entire repository to grasp the project's context.\n- [ ] Read the code in `$FILE_NAME` to understand its responsibilities and goals.\n- [ ] Based on the above, create a new test file for `$FILE_NAME`.\n- [ ] For each function in the file, write test cases for both happy paths and edge cases.\n- [ ] Review and improve the tests you've written from the perspective of `docs/testing.md`.\n- [ ] Finally, use the `gh` command to create a Pull Request.\n```\n\n### 2. Bulk-Generate Tasks with _Locus_\n\nNext, use a simple shell script to generate a task for every file you want to target.\n\n```bash\n# Generate a task for every .ts file in the `src` directory\nfor FILE in src/**/*.ts; do\n  # Replace the placeholder in the template with the actual filename\n  TASK_BODY=$(sed \"s/\\\\$FILE_NAME/$FILE/g\" test_template.md)\n  \n  # Create the task using `locus add` with --body option\n  locus add \"Create tests for $FILE\" --tags test,autogen --body \"$TASK_BODY\"\ndone\n```\n\n### 3. Provide Tasks to the Agent\n\nNow you have a list of clearly defined tasks. You can pass them one by one to your AI agent of choice.\n\n```bash\n# Get the content of a specific task and pipe it to your agent\nlocus read \"Create-tests-for-src-services-user-service.ts\" | your-ai-agent\n```\n\nThis method provides the AI agent with a narrow, well-defined scope for each run, which can help improve the consistency and reliability of its output.\n\n\u003c/details\u003e\n\n## Features\n\n- **Git-aware organization**: Tasks are automatically organized by Git repository (`~/locus/\u003cusername\u003e/\u003crepo\u003e/`)\n- **Markdown-based**: Tasks are stored as Markdown files with YAML frontmatter\n- **Flexible properties**: Support for tags, status, priority, and unlimited custom properties\n- **Smart file naming**: Automatic file naming with date, slug, and hash\n- **Task property management**: Get/set any property without editing files\n- **fzf-friendly output**: Default oneline format optimized for command-line filtering\n- **JSON output**: Machine-readable output for scripting and automation\n- **Internationalization**: Full support for English and Japanese interfaces\n- **Cross-platform**: Works on macOS, Linux, and Windows\n\n## Installation\n\n### Using Deno\n\n```bash\n# Install from JSR\ndeno install -g -A -n locus jsr:@tesso/locus\n```\n\n### Using NPM/NPX\n\n```bash\n# Run without installation\nnpx @tesso/locus --version\n\n# Install globally\nnpm install -g @tesso/locus\n```\n\n## Quick Start\n\n```bash\n# 1. Add your first task\nlocus add \"Fix authentication bug\" --tags bug,urgent --priority high\n\n# 2. List your tasks\nlocus list\n\n# 3. View a task\nlocus read \"Fix authentication bug\"\n\n# 4. Update task status\nlocus tags set \"Fix authentication bug\" status done\n\n# 5. Find tasks interactively with fzf\nlocus list | fzf --preview='locus read {7} --raw'\n```\n\n## Usage\n\n```\nCommands:\n\n  add     \u003ctitle\u003e     - Add a new task\n  edit    \u003cfileName\u003e  - Edit task content\n  list                - List tasks (default: oneline format)\n  tags                - Manage task file properties\n  set     \u003cfileName\u003e  - Set task properties (flexible key=value syntax)\n  get     \u003cfileName\u003e  - Get task properties\n  config              - Manage configuration\n  read    \u003cfileName\u003e  - Display task content (supports full paths)\n  path    \u003cfileName\u003e  - Show absolute path of task file\n  help                - Show help\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eCommand Examples\u003c/summary\u003e\n\n### Add a new task\n\n```bash\n# Basic usage\nlocus add \"Fix authentication bug\"\n\n# With body content using command substitution\nTASK_BODY=\"Need to fix the JWT token validation\"\nlocus add \"Fix authentication bug\" --body \"$TASK_BODY\"\n\n# With body content directly\nlocus add \"Fix bug\" --body \"Details about the bug fix\"\n\n# With tags and properties\nlocus add \"Implement dark mode\" --tags ui,feature --priority high --status in-progress\n\n# With custom properties using key=value syntax\nlocus add \"Database migration\" --tags backend assignee=alice estimate=3h\n\n# Create task without Git context\nlocus add \"Personal task\" --no-git\n\n# Output task info as JSON\nlocus add \"New feature\" --json\n```\n\n### Edit task content\n\n```bash\n# Edit existing task (appends by default)\nlocus edit \"fix-auth-bug\" --body \"Additional notes about the fix\"\n\n# Create new task if it doesn't exist\nlocus edit \"new-task\" --body \"Task description\"\n\n# Overwrite entire task content\nlocus edit \"update-readme\" --body \"New content\" --overwrite\n\n# Edit from stdin\necho \"Task updates from script\" | locus edit \"automated-task\" --body -\n\n# Edit without Git context\nlocus edit \"personal-note\" --body \"Update\" --no-git\n\n# Output result as JSON\nlocus edit \"task\" --body \"content\" --json\n```\n\n### List tasks\n\n```bash\n# List all tasks in current repository (default: oneline format)\nlocus list\n\n# Output format: [repository] [status] [priority] [title] [tags] [created] [path]\n# Example: myproject/api\ttodo\thigh\tFix auth bug\tbug,security\t2024-01-15\t/home/user/locus/myproject/api/fix-auth-bug.md\n\n# Use table format (previous default)\nlocus list --table\n\n# Filter by status\nlocus list --status todo\nlocus list --status in-progress\nlocus list --status done\n\n# Filter by priority\nlocus list --priority high\nlocus list --priority normal\nlocus list --priority low\n\n# Filter by tags\nlocus list --tags bug,critical\n\n# Sort tasks\nlocus list --sort created    # Sort by creation date (default)\nlocus list --sort status     # Sort by status\nlocus list --sort priority   # Sort by priority\nlocus list --sort title      # Sort by title\n\n# Group by repository\nlocus list --group-by-repo\n\n# Show detailed view\nlocus list --detail\n\n# List all tasks across repositories\nlocus list --all\n\n# Output as JSON\nlocus list --json\n```\n\n### Integration with fzf\n\nThe default oneline format is optimized for use with command-line filtering tools like [fzf](https://github.com/junegunn/fzf):\n\n```bash\n# Interactive task selection with preview\nlocus list | fzf --delimiter=$'\\t' \\\n  --with-nth=1,2,3,4 \\\n  --preview='locus read {7} --raw' \\\n  --bind='enter:execute(${EDITOR:-vim} {7})'\n\n# Filter todo tasks and open selected file\nlocus list --status todo | fzf | cut -f7 | xargs -I{} ${EDITOR:-vim} {}\n\n# Quick navigation to task directory\ncd $(locus list | fzf | cut -f7 | xargs dirname)\n\n# Search tasks by content and open\nlocus list | fzf --preview='locus read {7} --raw | head -20' | cut -f7 | xargs open\n\n# Copy task path to clipboard (macOS)\nlocus list | fzf | cut -f7 | pbcopy\n\n# Copy task path to clipboard (Linux)\nlocus list | fzf | cut -f7 | xclip -selection clipboard\n```\n\n### Manage task properties with tags command\n\n```bash\n# List all task files\nlocus tags list\n\n# Show properties of a specific file\nlocus tags list \"fix-auth-bug\"\n\n# Get a specific property\nlocus tags get \"fix-auth-bug\" status\n\n# Set/update a property\nlocus tags set \"fix-auth-bug\" status done\nlocus tags set \"fix-auth-bug\" priority high\n\n# Remove a property\nlocus tags rm \"fix-auth-bug\" assignee\n\n# Clear all properties\nlocus tags clear \"fix-auth-bug\"\n```\n\n### Flexible property management with set/get commands\n\n```bash\n# Set properties using key=value syntax\nlocus set \"fix-auth-bug\" status=done priority=high\nlocus set \"feature-task\" assignee=bob estimate=5h\n\n# Set multiple properties at once\nlocus set \"complex-task\" status=in-progress assignee=alice reviewer=bob due=tomorrow\n\n# Smart value parsing\nlocus set \"data-task\" count=42 active=true tags=backend,urgent\n\n# Date patterns\nlocus set \"deadline-task\" due=today start=tomorrow end=+7d\n\n# Get a specific property\nlocus get \"fix-auth-bug\" status\n# Output: done\n\n# Get all properties\nlocus get \"fix-auth-bug\"\n# Output:\n# date: 2024-01-15\n# created: 2024-01-15T10:00:00Z\n# status: done\n# priority: high\n\n# JSON output for scripting\nlocus get \"task\" --json\nlocus get \"task\" status --json\n```\n\n### Read task content\n\n```bash\n# Read a task file (automatic pager for long content)\nlocus read \"fix-auth-bug\"\n\n# Read with raw markdown (including frontmatter)\nlocus read \"implement-dark-mode\" --raw\n\n# Read without pager\nlocus read \"update-readme\" --pager never\n\n# Use specific pager\nlocus read \"long-task\" --pager less\n\n# Disable colored output\nlocus read \"task\" --no-color\n\n# Output as JSON for scripting\nlocus read \"add-tests\" --json\n\n# Read by absolute path\nlocus read /path/to/task.md\n```\n\n### Find task file paths\n\n```bash\n# Get the absolute path of a task\nlocus path \"fix-auth-bug\"\n\n# Search for task across all repositories\nlocus path \"implement-feature\" --all\n\n# Search by partial filename or title\nlocus path \"auth\"  # Finds files matching \"auth\" in name or title\n\n# Output as JSON with additional metadata\nlocus path \"task-name\" --json\n\n# Work without Git context\nlocus path \"task\" --no-git\n\n# Use in scripts or with other commands\ncat $(locus path \"my-task\")\neditor $(locus path \"todo-task\")\n```\n\n### Configuration\n\n```bash\n# Show current configuration\nlocus config show\nlocus config show --json  # JSON output\n\n# Show configuration file path\nlocus config path\n\n# Initialize configuration file\nlocus config init\nlocus config init --force  # Overwrite existing config\n```\n\n### Language Settings\n\nLocus supports both English and Japanese interfaces. The language can be configured in multiple ways:\n\n```bash\n# Set language via environment variable (highest priority)\nlocus add \"New task\"\n\n# Set language in configuration file\nlocus config init\n# Edit ~/.config/locus/settings.yml and set language.default to \"en\" or \"ja\"\n\n# The language detection order is:\n# 1. LOCUS_LANG environment variable\n# 2. Configuration file setting\n# 3. System LANG environment variable\n# 4. Default to English (\"en\")\n```\n\n### Output Formats\n\nMost commands support JSON output with the `--json` flag for scripting and automation:\n\n```bash\nlocus add \"task\" --json\nlocus list --json\nlocus read \"task\" --json\nlocus path \"task\" --json\nlocus config show --json\n```\n\n\u003c/details\u003e\n\n## Configuration\n\nConfiguration is stored in `~/.config/locus/settings.yml` (follows XDG Base Directory specification).\n\nFor detailed configuration documentation, see:\n\n- **[Configuration Guide](docs/configuration.md)** - Complete configuration reference\n- **[設定ガイド](docs/configuration_ja.md)** - 日本語版設定ガイド\n\n### Configuration Example\n\n```yaml\n# Task storage directory\ntask_directory: \"~/locus\"\n\n# Language settings\nlanguage:\n  default: \"en\" # Available: \"en\" (English) or \"ja\" (Japanese)\n\n# Git integration settings\ngit:\n  extract_username: true\n  username_from_remote: true\n\n# File naming configuration\nfile_naming:\n  pattern: \"{slug}.md\"\n  date_format: \"YYYY-MM-DD\"\n  hash_length: 8\n\n# Default values for new tasks\ndefaults:\n  status: \"todo\"\n  priority: \"normal\"\n  tags: []\n  custom: {}\n# Add your custom default properties here\n# Example: assignee: \"unassigned\"\n# Example: category: \"general\"\n```\n\n## Task File Format\n\nTasks are stored as Markdown files with YAML frontmatter:\n\n```markdown\n---\ndate: 2024-01-15\ncreated: 2024-01-15T10:30:00Z\ntags:\n  - feature\n  - backend\nstatus: in-progress\npriority: high\n# Custom properties\nassignee: alice\nestimate: 8h\nreviewer: bob\n---\n\n# Implement user authentication\n\nAdd JWT-based authentication to the API endpoints.\n\n## Requirements\n\n- [ ] Login endpoint\n- [ ] Token refresh mechanism\n- [ ] Logout functionality\n```\n\n## Development\n\n### Prerequisites\n\n- [Deno](https://deno.com/) \u003e= 2.0\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/tesso57/locus.git\ncd locus\n\n# Run in development mode\ndeno task dev\n\n# Run tests\ndeno task test\n\n# Build binaries\ndeno task compile\n```\n\n### Available Tasks\n\n- `deno task dev` - Run in development mode\n- `deno task test` - Run tests with coverage\n- `deno task lint` - Run linter\n- `deno task fmt` - Format code\n- `deno task check` - Run format check, lint, and tests\n- `deno task compile` - Build binaries for all platforms\n- `deno task install-local` - Install locally as 'locus' command\n\n### Direct Execution\n\nYou can also run the CLI directly without using tasks:\n\n```bash\n# Run with deno\ndeno run src/cli.ts\n\n# Run with npx (if Deno is installed via npm)\nnpx deno run src/cli.ts\n\n# Run directly from JSR\ndeno run jsr:@tesso/locus\n\n# Run with npx from JSR\nnpx @tesso/locus\n```\n\n## Documentation\n\n- **[Configuration Guide](docs/configuration.md)** - Comprehensive guide to configuring Locus\n- **[日本語版 README](docs/README_ja.md)** - Japanese version of this README\n- **[設定ガイド](docs/configuration_ja.md)** - Configuration guide in Japanese\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Author\n\n[tesso57](https://github.com/tesso57)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftesso57%2Flocus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftesso57%2Flocus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftesso57%2Flocus/lists"}