{"id":28545047,"url":"https://github.com/its-brianwithai/pewpewcli","last_synced_at":"2025-07-07T02:31:33.325Z","repository":{"id":288141946,"uuid":"962916975","full_name":"its-brianwithai/pewPewCLI","owner":"its-brianwithai","description":"Lightweight CLI tool enabling collaborative Markdown task list management between developers and AI agents.","archived":false,"fork":false,"pushed_at":"2025-06-17T00:56:48.000Z","size":86872,"stargazers_count":3,"open_issues_count":17,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-21T08:12:25.035Z","etag":null,"topics":["ai-agents","cli","collaboration","command-line","command-line-tool","developer-tools","javascript","llm","markdown","nodejs","productivity","task-management","terminal","typescript","workflow-automation"],"latest_commit_sha":null,"homepage":"https://www.ultrawideturbodevs.com/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/its-brianwithai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-08T21:51:32.000Z","updated_at":"2025-06-16T08:17:34.000Z","dependencies_parsed_at":"2025-05-07T01:44:04.578Z","dependency_job_id":null,"html_url":"https://github.com/its-brianwithai/pewPewCLI","commit_stats":null,"previous_names":["ultrawideturbodev/pewpewcli","its-brianwithai/pewpewcli"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/its-brianwithai/pewPewCLI","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/its-brianwithai%2FpewPewCLI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/its-brianwithai%2FpewPewCLI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/its-brianwithai%2FpewPewCLI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/its-brianwithai%2FpewPewCLI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/its-brianwithai","download_url":"https://codeload.github.com/its-brianwithai/pewPewCLI/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/its-brianwithai%2FpewPewCLI/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261088385,"owners_count":23107688,"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","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":["ai-agents","cli","collaboration","command-line","command-line-tool","developer-tools","javascript","llm","markdown","nodejs","productivity","task-management","terminal","typescript","workflow-automation"],"created_at":"2025-06-09T22:38:20.984Z","updated_at":"2025-07-07T02:31:33.319Z","avatar_url":"https://github.com/its-brianwithai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pewPewCLI ❤️ Agents' Fav Dev Tool 🔫\n\n[![Built to you by ultrawideturbodevs.com](https://img.shields.io/badge/Built%20to%20you%20by-ultrawideturbodevs.com-blue?style=for-the-badge\u0026logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyem0xIDE1aC0ydi0yaDJ2MnptMC00aC0yVjdoMnY2eiIvPjwvc3ZnPg==)](https://ultrawideturbodevs.com)\n\n[![npm version](https://badge.fury.io/js/pew-pew-cli.svg)](https://badge.fury.io/js/pew-pew-cli)\n\n![hero.png](https://raw.githubusercontent.com/ultrawideturbodev/pewPewCLI/main/assets/pngs/hero.png)\n\nLightweight CLI tool that enables collaborative local task file management between developers and AI agents.\n\n## 💻 Install\n\nEnsure you have Node.js and npm installed.\n\n```bash\nnpm install -g pew-pew-cli \u0026\u0026 pew init\n```\n\n## ⚙️ Configuration\n\n*   **Local:** `pew.yaml` in your project root (specific to the current project/directory)\n*   **Global:** `~/.pew/pew.yaml` (user-level settings)\n\nThe configuration uses a feature-based structure, with top-level keys for different aspects of the application:\n\n### `pew.yaml` Structure\n\n```yaml\ntasks:\n  # List of files scanned by 'pew next task' and offered by 'pew reset tasks'\n  # Processed in the order listed. Absolute paths also work.\n  all:\n    - relative/path/to/tasks.md\n    - another-tasks.md\n    # - /absolute/path/to/tasks.md\n  \n  # Default primary task file\n  primary: relative/path/to/tasks.md\n  \n  # Default target file for 'pew paste tasks'\n  # If omitted, defaults to the primary task file\n  paste: relative/path/to/tasks.md\n\nupdates:\n  # Timestamp for last update check\n  lastUpdateCheckTimestamp: 0\n```\n\nAll paths in the configuration are resolved relative to the location of the `pew.yaml` file. If a configuration key is missing, hardcoded defaults are provided automatically.\n\n## 📝 Commands\n\n| Command           | Description                                                                  | Options                                                                                                                                         |\n|:------------------|:-----------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------|\n| `pew init`        | Initialize the `pewPewCLI` project structure in the current directory.       | `-f, --force`: Force initialization even if `.pew` directory exists.                                                                            |\n| `pew set path`    | Set a configuration value for a path (currently only `tasks`).               | `--field \u003cfield\u003e`: Field to set (only `tasks`).\u003cbr\u003e`--value \u003cvalue\u003e`: Path value to set.\u003cbr\u003e`-g, --global`: Set in global config (`~/.pew`).    |\n| `pew paste tasks` | Paste clipboard content into the configured task file.                       | \u003cmode\u003e Paste mode (`--override`, `--append`, `--insert`). Prompts if omitted.\u003cbr\u003e`--path \u003cvalue\u003e`: Specify target file path, overriding config. |\n| `pew next task`   | Marks the current task (`👉`) complete and displays the next available task. | _None_                                                                                                                                          |\n| `pew reset tasks` | Uncheck all completed tasks (`[x]`) in configured task files interactively.  | _None_                                                                                                                                          |\n| `pew update`      | Check for updates and install the latest version of `pew-pew-cli`.           | _None_                                                                                                                                          |\n\n### 📂 `pew init`\n\nCreates the `pew.yaml` file in the current directory and prompts for the primary tasks file path. This file will be created if it doesn't exist.\n\n```bash\n# Interactive initialization\npew init\n\n# Force initialization without prompts (uses defaults)\npew init --force\n```\n\n![pew-init-demo.gif](https://raw.githubusercontent.com/ultrawideturbodev/pewPewCLI/main/assets/gifs/pew-init-demo.gif)\n\n### 📂 `pew paste tasks`\n\nReads content from your system clipboard and writes it to a task file. By default, it targets the file specified by `paste-tasks` in `paths.yaml` (or falls back to the first file under `tasks:`). You can specify the mode (`overwrite`, `append`, `insert`) or the target path using options. If no mode is specified, it will prompt interactively.\n\n```bash\n# Paste and overwrite the default task file\npew paste tasks --overwrite\n\n# Append clipboard content to a specific file\npew paste tasks --path specific/project/tasks.md --append\n\n# Run interactively to choose mode\npew paste tasks\n```\n\n![pew-paste-task-demo.gif](https://raw.githubusercontent.com/ultrawideturbodev/pewPewCLI/main/assets/gifs/pew-paste-task-demo.gif)\n\n### 👉 `pew next task`\n\nThis is the core command for progressing through your task lists. It finds the current task marked with `👉`, marks it as complete (`- [ ]` -\u003e `- [x]`), removes the `👉`, finds the next available incomplete task (`- [ ]`) across all files configured in `paths.yaml` (in order), adds the `👉` prefix to it, and displays the context of that new task.\n\n```bash\n# Process the current task and move to the next one\npew next task\n```\n\n![pew-next-task-demo-small.gif](https://raw.githubusercontent.com/ultrawideturbodev/pewPewCLI/main/assets/gifs/pew-next-task-demo-small.gif)\n\n### 📂 `pew reset tasks`\n\nResets completed tasks within your configured checklists. This command interactively prompts you to select which of the task files listed in your `paths.yaml` you want to reset. For each selected file, it changes all completed task markers (`- [x]` or `- [X]`) back to incomplete (`- [ ]`) and removes the `👉` prefix if present.\n\nIt helps restart repeatable workflows (like daily checklists, QA runs) without manual editing.\n\n```bash\n# Interactively select configured task files to reset\npew reset tasks\n```\n\nThe prompt will show a summary of tasks within each file to help you select.\n\n![pew-reset-tasks-demo.gif](https://raw.githubusercontent.com/ultrawideturbodev/pewPewCLI/main/assets/gifs/pew-reset-tasks-demo.gif)\n\n### ✨ `pew update`\n\nChecks if a newer version of `pew-pew-cli` is available on npm and prompts you to install it if found.\n\n```bash\n# Check for and install updates\npew update\n```\n\n## 📝 Pew Pipelines (`pew next task`)\n\nYou can manage different checklists across multiple files (e.g., main dev tasks, QA checklist).\n\n1. **Configure `paths.yaml`:** List all relevant files under the `tasks:` key in order.\n2. **Run `pew next task`:** pewPewCLI processes tasks sequentially through the files listed.\n3. **Reset Checklists:** Use `pew reset tasks` to uncheck completed items when you want to restart a workflow (like the QA checklist).\n\n![pew-next-task-flow.gif](https://raw.githubusercontent.com/ultrawideturbodev/pewPewCLI/main/assets/gifs/pew-next-task-flow.gif)\n\n## 📦 Dependencies\n\nKey dependencies include:\n\n*   [commander](https://github.com/tj/commander.js/): Command-line argument parsing.\n*   [inquirer](https://github.com/SBoudrias/Inquirer.js/): Interactive CLI prompts.\n*   [clipboardy](https://github.com/sindresorhus/clipboardy): Clipboard access.\n*   [js-yaml](https://github.com/nodeca/js-yaml): YAML parsing/serialization.\n*   [latest-version](https://github.com/sindresorhus/latest-version): Fetches the latest version of an npm package.\n*   [chalk](https://github.com/chalk/chalk): Terminal string styling (used indirectly).\n\n## 🤝 Contributing\n\nContributions are welcome! We appreciate bug reports, feature suggestions, documentation improvements, and code contributions.\n\nPlease refer to the [CONTRIBUTING.md](CONTRIBUTING.md) file for detailed guidelines on how to contribute, including setting up your development environment, commit signing requirements, and the pull request process.\n\nWe adhere to the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).\n\n## 📄 License\n\nThis project is proprietary software, owned and distributed by Ultra Wide Turbo Company. All rights reserved.\n\nUsage is subject to the terms outlined in the [LICENSE](https://github.com/ultrawideturbodev/pewPewCLI/blob/main/LICENSE.md) file and requires a separate commercial agreement for any commercial use. Please review the [LICENSE](https://github.com/ultrawideturbodev/pewPewCLI/blob/main/LICENSE.md) file for details.\n\n## 📞 Contact \u0026 Support\n\n*   **Bugs \u0026 Feature Requests:** Please use the [GitHub Issues](https://github.com/ultrawideturbodev/pew-pew-cli/issues) tracker. Use the provided templates for effective reporting.\n*   **Questions \u0026 Discussions:** Use the [GitHub Discussions](https://github.com/ultrawideturbodev/pew-pew-cli/discussions) tab for general questions, usage help, or sharing ideas (if Discussions are enabled).\n*   **Security Vulnerabilities:** Please report privately according to the [SECURITY.md](SECURITY.md) policy.\n*   **General Info:** Visit [ultrawideturbodevs.com](https://ultrawideturbodevs.com) for more context.\n\n## 🏢 Ownership\n\n`pew-pew-cli` is owned and maintained by the Ultra Wide Turbo Company.\n\n## 🤖 Example Agent Prompt\n\nHere's a prompt you can adapt for an AI agent to use this tool once initialized in a project:\n\n```\nYou are an AI assistant tasked with executing the next available milestones and set of tasks outlined in the provided plan. Follow these instructions carefully:\n\n1.  **Review Task Plan:** First, carefully review the content of the {{TASK_FILE_LOCATION}} (typically `.pew/tasks.md`).\n\n2.  **Understand Context:**\n    *   Your goal is to complete the next available milestone (specifically Milestone `{{MILESTONE_NUMBER}}`) and its associated tasks sequentially.\n    *   You must follow the plan exactly as specified in `{{TASK_FILE_LOCATION}}` without adding, removing, or changing steps or requirements unless explicitly instructed by a task.\n\n3.  **Identify Next Task:**\n    *   Locate Milestone `{{MILESTONE_NUMBER}}` in the `{{TASK_FILE_LOCATION}}` file.\n    *   Identify the first uncompleted task listed under this milestone.\n    *   Use the `pew next task` command to confirm and retrieve the details of this first task.\n\n4.  **Research Project Context:**\n    *   Based on the output of `pew next task`, thoroughly scan all related project files to gain a deep understanding of the task's requirements and the project's context.\n\n5.  **Execute Tasks Sequentially:**\n    *   Complete each task strictly in the order presented.\n    *   Use the `pew next task` command *after* successfully completing the current task to mark it done and get the next one.\n    *   Do not skip any tasks or alter their prescribed order.\n\n6.  **Milestone Completion Review:**\n    *   After completing *all* tasks for Milestone `{{MILESTONE_NUMBER}}`, review the implemented work for correctness and consistency.\n\n7.  **Completion and Next Steps:**\n    *   Once all tasks for the specified milestone are successfully completed and reviewed/fixed, ask the user for the next set of instructions.\n\n**Always remember:**\n*   Stick rigorously to the plan.\n*   Focus exclusively on the tasks for the specified milestone.\n*   Update the task file using `pew next task` immediately after completing each task.\n*   Ensure high-quality output (code, documentation, etc.).\n*   Run `pew` commands autonomously as needed (\"yolo mode is on\").\n\nBegin your work by reading the `{{TASK_FILE_LOCATION}}`. Then, identify and start the first task for Milestone `{{MILESTONE_NUMBER}}` using `pew next task`.\n\nMILESTONE_NUMBER = ALL\nTASK_FILE_LOCATION = .pew/tasks.md\n\nACT\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fits-brianwithai%2Fpewpewcli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fits-brianwithai%2Fpewpewcli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fits-brianwithai%2Fpewpewcli/lists"}