{"id":32720293,"url":"https://github.com/iishyfishyy/please","last_synced_at":"2026-04-16T19:34:37.830Z","repository":{"id":320986726,"uuid":"1083988011","full_name":"iishyfishyy/please","owner":"iishyfishyy","description":"A CLI tool to convert natural language queries into terminal commands. Supports custom commands via RAG.","archived":false,"fork":false,"pushed_at":"2025-10-27T05:47:41.000Z","size":121,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-27T06:22:47.755Z","etag":null,"topics":["cli","comands","language","natural","rag","terminal"],"latest_commit_sha":null,"homepage":"","language":"Go","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/iishyfishyy.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":"2025-10-27T03:56:01.000Z","updated_at":"2025-10-27T05:47:45.000Z","dependencies_parsed_at":"2025-10-27T06:33:06.283Z","dependency_job_id":null,"html_url":"https://github.com/iishyfishyy/please","commit_stats":null,"previous_names":["iishyfishyy/please"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/iishyfishyy/please","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iishyfishyy%2Fplease","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iishyfishyy%2Fplease/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iishyfishyy%2Fplease/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iishyfishyy%2Fplease/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iishyfishyy","download_url":"https://codeload.github.com/iishyfishyy/please/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iishyfishyy%2Fplease/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":282349848,"owners_count":26654800,"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-11-02T02:00:06.609Z","response_time":64,"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","comands","language","natural","rag","terminal"],"created_at":"2025-11-02T20:00:53.529Z","updated_at":"2025-11-02T20:02:27.131Z","avatar_url":"https://github.com/iishyfishyy.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `please` AI\n\n[![GitHub Release](https://img.shields.io/github/v/release/iishyfishyy/please)](https://github.com/iishyfishyy/please/releases)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/iishyfishyy/please/release.yml)](https://github.com/iishyfishyy/please/actions)\n[![License](https://img.shields.io/github/license/iishyfishyy/please)](LICENSE)\n[![Go Version](https://img.shields.io/github/go-mod/go-version/iishyfishyy/please)](go.mod)\n\n`please` converts your natural language queries into the respective terminal command.\n\n![Demo of please in action](./please-demo.gif)\n\nUnlike other similar tools that require API keys (which usually require a purchase of separate credits), `please` is powered by headless mode of agents you have installed on your machine.\n\nYou can teach `please` about your internal/proprietary tools by configuring it with your docuentation. `please` can use simple keyword matching and/or RAG to answer queries based on your documentation. The tool can generate embeddings locally (Ollama) or via OpenAI's embeddings API (requires your own OpenAI API key).\n\n**Currently, only Claude Code is supported.**\n\nI plan to add the following in the near future, as they both also support headless mode.\n- Codex CLI\n- Block's Goose CLI\n\n## Features\n\n- **Natural language commands** - No need to remember complex syntax\n- **Custom commands** - Teach `please` about your internal/proprietary tools\n- **Interactive confirmation** - Review commands before execution\n- **Iterative refinement** - Iterate \u0026 modify generated commands with natural language\n- **Command history** - Tracks all your requests and executions\n- **Smart matching** - Keyword or semantic search for custom commands\n\n## Installation\n\n### Prerequisites\n\n- Claude CLI ([installation instructions](https://github.com/anthropics/claude-cli))\n\nFirst, install and authenticate with Claude CLI:\n\n```bash\n# Install Claude CLI (follow official instructions)\n# Then authenticate:\nclaude\n```\n\n### Quick Install\n\nChoose your preferred installation method:\n\n#### Homebrew (macOS/Linux)\n\n```bash\nbrew install iishyfishyy/tap/please\n```\n\n#### Install Script (macOS/Linux/Windows)\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/iishyfishyy/please/main/install.sh | bash\n```\n\n#### Go Install\n\n```bash\ngo install github.com/iishyfishyy/please/cmd/please@latest\n```\n\n#### Download Binary\n\nDownload the latest release for your platform from the [releases page](https://github.com/iishyfishyy/please/releases/latest).\n\n#### Build from Source\n\n```bash\ngit clone https://github.com/iishyfishyy/please.git\ncd please\ngo build -o please ./cmd/please\nsudo mv please /usr/local/bin/\n```\n\n## Quick Start\n\n### 1. Configure\n\nRun the configuration wizard:\n\n```bash\nplease configure\n```\n\nThis will:\n- Check if Claude CLI is installed and authenticated\n- Verify the connection is working\n- Save your configuration to `~/.please/config.json`\n\n### 2. Use it\n\nSimply prefix your request with `please`:\n\n```bash\nplease \"list all files\"\nplease \"find all javascript files modified in the last week\"\nplease \"show disk usage sorted by size\"\nplease \"create a git branch called feature-x\"\nplease \"compress all images in this directory\"\n```\n\n### 3. Review and execute\n\n`please` will:\n1. Generate the appropriate command\n2. Show you the command for review\n3. Ask what you want to do (keyboard shortcuts):\n   - **[r] Run it** - Execute the command immediately\n   - **[e] Explain** - Get a detailed explanation of what the command does\n   - **[m] Modify it** - Refine the command with natural language\n   - **[c] Copy to clipboard** - Copy the command without running\n   - **[q] Cancel** - Exit without running anything\n\n## Configuration\n\nConfiguration is stored in `~/.please/config.json`.\n\n### Complete Configuration Schema\n\n```json\n{\n  \"agent\": \"claude-code\",\n  \"custom_commands\": {\n    \"enabled\": true,\n    \"provider\": \"ollama\",\n    \"matching\": {\n      \"strategy\": \"hybrid\",\n      \"keyword_threshold\": 50,\n      \"max_docs_per_request\": 3,\n      \"token_budget\": 1500\n    },\n    \"ollama\": {\n      \"url\": \"http://localhost:11434\",\n      \"model\": \"nomic-embed-text\",\n      \"dimensions\": 384\n    },\n    \"openai\": {\n      \"api_key\": \"\",\n      \"api_key_env\": \"OPENAI_API_KEY\",\n      \"use_env_var\": true,\n      \"model\": \"text-embedding-3-small\",\n      \"dimensions\": 1536\n    }\n  }\n}\n```\n\n### Configuration Options\n\n**`agent`** (string, required)\n- Currently only `\"claude-code\"` is supported\n- Future: `\"codex\"`, `\"goose\"`\n\n**`custom_commands.enabled`** (boolean)\n- `true`: Enable custom command documentation\n- `false`: Disable custom commands feature\n\n**`custom_commands.provider`** (string)\n- `\"none\"`: Keyword-only matching (fast, no dependencies)\n- `\"ollama\"`: Local embeddings (private, free)\n- `\"openai\"`: Cloud embeddings (accurate, requires API key)\n\n**`custom_commands.matching.strategy`** (string)\n- `\"keyword\"`: Fast keyword matching only\n- `\"semantic\"`: Semantic search only (requires provider)\n- `\"hybrid\"`: Try keyword first, fallback to semantic (recommended)\n\n**`custom_commands.matching.keyword_threshold`** (integer)\n- Minimum score for keyword matches (default: 50)\n- Lower = more matches, higher = stricter matching\n\n**`custom_commands.matching.max_docs_per_request`** (integer)\n- Maximum custom commands to include in context (default: 3)\n- Higher = more context, but uses more tokens\n\n**`custom_commands.matching.token_budget`** (integer)\n- Maximum tokens for custom command context (default: 1500)\n- Controls how much documentation is sent to the LLM\n\n### Example Configurations\n\n**Minimal (keyword-only, no embeddings)**:\n```json\n{\n  \"agent\": \"claude-code\",\n  \"custom_commands\": {\n    \"enabled\": true,\n    \"provider\": \"none\",\n    \"matching\": {\n      \"strategy\": \"keyword\"\n    }\n  }\n}\n```\n\n**Local with Ollama (privacy-focused)**:\n```json\n{\n  \"agent\": \"claude-code\",\n  \"custom_commands\": {\n    \"enabled\": true,\n    \"provider\": \"ollama\",\n    \"matching\": {\n      \"strategy\": \"hybrid\",\n      \"keyword_threshold\": 50,\n      \"max_docs_per_request\": 3\n    },\n    \"ollama\": {\n      \"url\": \"http://localhost:11434\",\n      \"model\": \"nomic-embed-text\"\n    }\n  }\n}\n```\n\n**Cloud with OpenAI (most accurate)**:\n```json\n{\n  \"agent\": \"claude-code\",\n  \"custom_commands\": {\n    \"enabled\": true,\n    \"provider\": \"openai\",\n    \"matching\": {\n      \"strategy\": \"hybrid\",\n      \"max_docs_per_request\": 3\n    },\n    \"openai\": {\n      \"api_key_env\": \"OPENAI_API_KEY\",\n      \"use_env_var\": true,\n      \"model\": \"text-embedding-3-small\"\n    }\n  }\n}\n```\n\n**Note**: Authentication for Claude is handled by the Claude CLI, so no API keys are stored in config for the main agent. OpenAI API keys (for embeddings only) can be stored in environment variables (recommended) or in the config file.\n\n## Custom Commands\n\n### Overview\n\nCustom commands let you teach `please` about proprietary, internal, or specialized tools that Claude doesn't know about. You simply create markdown documentation files with examples, and `please` uses them to generate accurate commands.\n\n**Perfect for**:\n- Internal company tools and deployment systems\n- Custom scripts and proprietary utilities\n- Specialized domain-specific tools\n- Non-standard command-line applications\n\n### How It Works\n\n```\n1. You create: ~/.please/commands/deploy-tool.md\n   (Contains examples: \"deploy to staging\" → deploy-tool --env=staging)\n\n2. You run: please index\n   (Indexes your documentation for fast lookup)\n\n3. You use: please \"deploy my app to staging\"\n\n4. please finds your docs, sends context to Claude\n\n5. Claude generates: deploy-tool --env=staging --confirm\n```\n\n### Quick Start\n\n**Step 1: Configure custom commands**\n\n```bash\nplease configure\n```\n\nYou'll be prompted to choose an embedding provider:\n- **None**: Fast keyword-only matching, no setup required\n- **Ollama**: Local embeddings, 100% private, free (recommended for privacy)\n- **OpenAI**: Cloud embeddings, most accurate (requires API key)\n\n**Step 2: Create a documentation file**\n\nCreate `~/.please/commands/deploy-tool.md`:\n\n```markdown\n---\ncommand: deploy-tool\naliases: [\"deploy\", \"dt\"]\nkeywords: [\"deploy\", \"staging\", \"production\", \"release\"]\npriority: high\n---\n\n# Internal Deployment Tool\n\nOur custom deployment tool for managing releases.\n\n## Examples\n\n**User**: \"deploy to staging\"\n**Command**: `deploy-tool --env=staging --confirm`\n\n**User**: \"deploy version 1.2.3 to production\"\n**Command**: `deploy-tool --env=production --version=1.2.3 --confirm`\n\n**User**: \"rollback production\"\n**Command**: `deploy-tool --env=production --rollback`\n```\n\n**Step 3: Index your commands**\n\n```bash\nplease index\n```\n\n**Step 4: Use it!**\n\n```bash\n$ please \"deploy to staging\"\n\nGenerated command:\n  deploy-tool --env=staging --confirm\n\nWhat would you like to do (keyboard shortcuts):\n  [r] Run it\n  [e] Explain\n  [m] Modify it\n  [c] Copy to clipboard\n  [q] Cancel\n```\n\n### Documentation File Format\n\nCreate markdown files in `~/.please/commands/{tool-name}.md` with YAML frontmatter and examples:\n\n**Required fields**:\n```markdown\n---\ncommand: kubectl              # Primary command name (required)\n---\n```\n\n**Recommended fields**:\n```markdown\n---\ncommand: kubectl\naliases: [\"k8s\", \"kube\"]      # Alternative names\nkeywords: [\"kubernetes\", \"pods\", \"deployments\", \"k8s\"]\npriority: high                # high/medium/low (affects ranking)\ncategories: [\"devops\"]        # For organization\n---\n\n# Brief Description\n\nWhat this tool does in 1-2 sentences.\n\n## Examples\n\n**User**: \"show all pods\"\n**Command**: `kubectl get pods`\n\n**User**: \"get logs from nginx\"\n**Command**: `kubectl logs nginx`\n\n**User**: \"describe deployment myapp\"\n**Command**: `kubectl describe deployment myapp`\n```\n\n**Tips for great documentation**:\n- Add 10-15 diverse examples covering common use cases\n- Include keywords that users might naturally say (synonyms, abbreviations)\n- Use `priority: high` for your most-used commands\n- Keep descriptions concise - examples are more important\n\n### Matching Strategies\n\nChoose the right strategy for your needs:\n\n| Strategy | Speed | Accuracy | Setup | When to Use |\n|----------|-------|----------|-------|-------------|\n| **Keyword** | Fast | OK | None | Exact keyword matches, offline use |\n| **Hybrid** | Medium | Best | Ollama/OpenAI | Most use cases (recommended) |\n| **Semantic** | Slower | Best | Ollama/OpenAI | Complex queries, synonyms matter |\n\n**Keyword**: Matches based on exact words in your frontmatter (command, keywords, aliases)\n- No setup, works offline\n- Very fast\n- Misses synonyms (\"k8s\" won't match \"kubernetes\" unless you add it to aliases)\n\n**Hybrid**: Tries keyword first, falls back to semantic if no good matches\n- Fast when keywords match\n- Understands synonyms and paraphrasing\n- Best of both worlds\n- Requires Ollama or OpenAI setup\n\n**Semantic**: Always uses embeddings and vector similarity\n- Best for natural language understanding\n- Finds relevant docs even with different wording\n- Slower than keyword\n- Requires Ollama or OpenAI setup\n\n**Configuration**:\n```json\n{\n  \"custom_commands\": {\n    \"matching\": {\n      \"strategy\": \"hybrid\",          // or \"keyword\" or \"semantic\"\n      \"keyword_threshold\": 50,       // Minimum score for keyword matches\n      \"max_docs_per_request\": 3      // How many docs to send to Claude\n    }\n  }\n}\n```\n\n### Embedding Providers\n\nChoose between local privacy or cloud accuracy:\n\n#### Ollama (Local \u0026 Private)\n\n**Pros**:\n- 100% private - no data leaves your machine\n- Free forever, no API costs\n- Fast (~50-100ms per search)\n- Works offline\n\n**Cons**:\n- Requires installation (~2GB disk space)\n- Slightly less accurate than OpenAI\n\n**Setup**:\n```bash\n# macOS\nbrew install ollama\n\n# Linux\ncurl -fsSL https://ollama.com/install.sh | sh\n\n# Start Ollama\nollama serve\n\n# Configure please\nplease configure\n# Select \"Local (Ollama)\" when prompted\n```\n\nModel: `nomic-embed-text` (384 dimensions, auto-downloaded)\n\n#### OpenAI (Cloud \u0026 Accurate)\n\n**Pros**:\n- Most accurate semantic matching\n- No local installation needed\n- Very cheap ($0.02 per 1M tokens ≈ $0.0001 per index)\n\n**Cons**:\n- Requires API key and account\n- Data sent to OpenAI servers\n- Requires internet connection\n\n**Setup**:\n```bash\n# Get API key from https://platform.openai.com/api-keys\n\n# Option 1: Environment variable (recommended)\nexport OPENAI_API_KEY=\"sk-...\"\n\n# Option 2: Store in config (less secure)\nplease configure\n# Select \"OpenAI API\" and enter key when prompted\n```\n\nModel: `text-embedding-3-small` (1536 dimensions)\n\n#### None (Keyword-Only)\n\n**Pros**:\n- No setup required\n- Fastest option\n- Works offline\n- No dependencies\n\n**Cons**:\n- Less accurate than semantic search\n- Misses synonyms and paraphrasing\n\n**Use when**: You have good keywords and exact matching is sufficient\n\n### Available Commands\n\n```bash\n# Index or reindex your documentation\nplease index\n# Output: \"✓ Indexed 5 commands from ~/.please/commands/\"\n\n# List all indexed commands with details\nplease list-commands\n# Shows: command names, aliases, example counts, files\n\n# Configure or reconfigure settings\nplease configure\n# Interactive wizard for agent and custom commands\n```\n\n### Best Practices\n\n**Writing great documentation**:\n\n1. **10-15 diverse examples** - Cover common use cases and variations\n   ```markdown\n   **User**: \"deploy to prod\"\n   **User**: \"deploy v1.2.3 to production\"\n   **User**: \"rollback production to previous version\"\n   ```\n\n2. **Rich keywords** - Think like your users\n   ```yaml\n   keywords: [\"deploy\", \"release\", \"push\", \"ship\", \"prod\", \"staging\"]\n   ```\n\n3. **Useful aliases** - Alternative names people might use\n   ```yaml\n   aliases: [\"deploy\", \"dt\", \"release-tool\"]\n   ```\n\n4. **Set priorities** - Help ranking for your most-used tools\n   ```yaml\n   priority: high  # for daily-use tools\n   priority: medium  # for occasional tools\n   priority: low  # for rarely-used tools\n   ```\n\n5. **Keep it updated** - Reindex when you make changes\n   ```bash\n   # Edit your .md files, then:\n   please index\n   ```\n\n### Troubleshooting\n\n**Problem: \"No custom commands found\"**\n\n```bash\n# Check if commands directory exists\nls ~/.please/commands/\n# Should show your .md files\n\n# Check if custom commands are enabled\ncat ~/.please/config.json\n# Look for \"enabled\": true\n\n# Try reindexing\nplease index\n```\n\n**Problem: \"Failed to connect to Ollama\"**\n\n```bash\n# Check if Ollama is running\ncurl http://localhost:11434/api/tags\n\n# If not running, start it\nollama serve\n\n# Or on macOS (if installed as service)\nbrew services start ollama\n```\n\n**Problem: \"Commands not matching my queries\"**\n\n**Solution 1**: Add more keywords\n```yaml\n# Before\nkeywords: [\"deploy\"]\n\n# After\nkeywords: [\"deploy\", \"release\", \"push\", \"ship\", \"staging\", \"prod\", \"production\"]\n```\n\n**Solution 2**: Add more examples\n```markdown\n# Add variations of how users might ask\n**User**: \"push to prod\"\n**User**: \"ship to production\"\n**User**: \"release to staging environment\"\n```\n\n**Solution 3**: Try a different strategy\n```bash\n# Edit ~/.please/config.json\n{\n  \"custom_commands\": {\n    \"matching\": {\n      \"strategy\": \"semantic\",  // Instead of \"keyword\"\n      \"keyword_threshold\": 30  // Lower threshold (default: 50)\n    }\n  }\n}\n```\n\n**Problem: \"OpenAI API authentication failed\"**\n\n```bash\n# Check environment variable\necho $OPENAI_API_KEY\n\n# If empty, set it\nexport OPENAI_API_KEY=\"sk-your-key-here\"\n\n# Or reconfigure\nplease configure\n```\n\n## Command History\n\nAll requests and executions are logged to `~/.please/history.json`:\n\n```json\n{\n  \"entries\": [\n    {\n      \"timestamp\": \"2025-01-15T10:30:00Z\",\n      \"original_request\": \"find large files\",\n      \"final_command\": \"find . -type f -size +100M\",\n      \"executed\": true,\n      \"modifications\": []\n    }\n  ]\n}\n```\n\n## Tips\n\n- Be specific about what you want to accomplish\n- You can chain operations in your request\n- The tool understands context about your OS and shell\n\n## Safety\n\n`please` always shows you the command before execution and asks for confirmation. However:\n\n- **Review commands carefully** before running\n- **Understand what the command does** before confirming\n- **Be cautious with destructive operations** (rm, dd, etc.)\n- **Backup important data** before running unfamiliar commands\n\n## Development\n\n### Project Structure\n\n```\nplease/\n├── cmd/\n│   └── please/              # Main CLI entry point\n├── internal/\n│   ├── agent/               # LLM agent implementations\n│   ├── config/              # Configuration management\n│   ├── customcmd/           # Custom commands RAG system\n│   │   ├── embeddings/      # Embedding providers (Ollama, OpenAI)\n│   │   └── vectorstore/     # Vector storage and similarity search\n│   ├── executor/            # Safe command execution\n│   ├── history/             # Command history tracking\n│   └── ui/                  # Interactive prompts and display\n├── templates/               # Template files\n├── CLAUDE.md                # Project documentation for Claude\n├── README.md                # This file\n└── go.mod                   # Go module definition\n```\n\n## Roadmap\n\n### Planned\n- [ ] Support for additional LLM providers (Codex, Goose, etc.)\n- [ ] Command suggestions based on history\n- [ ] Multi-step command workflows\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a PR.\n\n---\n\n**Note**: This tool executes shell commands on your system. Always review generated commands before running them. Use at your own risk.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiishyfishyy%2Fplease","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiishyfishyy%2Fplease","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiishyfishyy%2Fplease/lists"}