@qoder-ai/qodercli 0.2.3 → 0.2.4-beta

package/README.md

@@ -1,13 +1,38 @@
 # qodercli
 
-qodercli is an open-source AI agent that brings the power of Gemini directly
+Gemini CLI is an open-source AI agent that brings the power of Gemini directly
 into your terminal. It provides lightweight access to Gemini, giving you the
 most direct path from your prompt to our model.
 
+Learn all about Gemini CLI in our [documentation](https://geminicli.com/docs/).
 
+## 🚀 Why Gemini CLI?
+
+- **🎯 Free tier**: 60 requests/min and 1,000 requests/day with personal Google
+  account.
+- **🧠 Powerful Gemini 3 models**: Access to improved reasoning and 1M token
+  context window.
+- **🔧 Built-in tools**: Google Search grounding, file operations, shell
+  commands, web fetching.
+- **🔌 Extensible**: MCP (Model Context Protocol) support for custom
+  integrations.
+- **💻 Terminal-first**: Designed for developers who live in the command line.
+- **🛡️ Open source**: Apache 2.0 licensed.
 
 ## 📦 Installation
 
+See
+[Gemini CLI installation, execution, and releases](https://www.geminicli.com/docs/get-started/installation)
+for recommended system specifications and a detailed installation guide.
+
+### Quick Install
+
+#### Run instantly with npx
+
+```bash
+# Using npx (no installation required)
+npx @qoder-ai/qodercli
+```
 
 #### Install globally with npm
 
@@ -15,6 +40,50 @@ most direct path from your prompt to our model.
 npm install -g @qoder-ai/qodercli
 ```
 
+#### Install with Anaconda (for restricted environments)
+
+```bash
+# Create and activate a new environment
+conda create -y -n gemini_env -c conda-forge nodejs
+conda activate gemini_env
+
+# Install qodercli globally via npm (inside the environment)
+npm install -g @qoder-ai/qodercli
+```
+
+## Release Channels
+
+See [Releases](https://www.geminicli.com/docs/changelogs) for more details.
+
+### Preview
+
+New preview releases will be published each week at UTC 23:59 on Tuesdays. These
+releases will not have been fully vetted and may contain regressions or other
+outstanding issues. Please help us test and install with `preview` tag.
+
+```bash
+npm install -g @qoder-ai/qodercli@preview
+```
+
+### Stable
+
+- New stable releases will be published each week at UTC 20:00 on Tuesdays, this
+  will be the full promotion of last week's `preview` release + any bug fixes
+  and validations. Use `latest` tag.
+
+```bash
+npm install -g @qoder-ai/qodercli@latest
+```
+
+### Nightly
+
+- New releases will be published each day at UTC 00:00. This will be all changes
+  from the main branch as represented at time of release. It should be assumed
+  there are pending validations and issues. Use `nightly` tag.
+
+```bash
+npm install -g @qoder-ai/qodercli@nightly
+```
 
 ## 📋 Key Features
 
@@ -34,10 +103,266 @@ npm install -g @qoder-ai/qodercli
 
 ### Advanced Capabilities
 
-- Ground your queries with built-infor real-time
+- Ground your queries with built-in
+  [Google Search](https://ai.google.dev/gemini-api/docs/grounding) for real-time
   information
 - Conversation checkpointing to save and resume complex sessions
 - Custom context files (GEMINI.md) to tailor behavior for your projects
 
+## 🔐 Authentication Options
+
+Choose the authentication method that best fits your needs:
+
+### Option 1: Sign in with Google (OAuth login using your Google Account)
+
+**✨ Best for:** Individual developers as well as anyone who has a Gemini Code
+Assist License. (see
+[quota limits and terms of service](https://cloud.google.com/gemini/docs/quotas)
+for details)
+
+**Benefits:**
+
+- **Free tier**: 60 requests/min and 1,000 requests/day
+- **Gemini 3 models** with 1M token context window
+- **No API key management** - just sign in with your Google account
+- **Automatic updates** to latest models
+
+#### Start Gemini CLI, then choose _Sign in with Google_ and follow the browser authentication flow when prompted
+
+```bash
+qodercli
+```
+
+#### If you are using a paid Code Assist License from your organization, remember to set the Google Cloud Project
+
+```bash
+# Set your Google Cloud Project
+export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
+qodercli
+```
+
+### Option 2: Gemini API Key
+
+**✨ Best for:** Developers who need specific model control or paid tier access
+
+**Benefits:**
+
+- **Free tier**: 1000 requests/day with Gemini 3 (mix of flash and pro)
+- **Model selection**: Choose specific Gemini models
+- **Usage-based billing**: Upgrade for higher limits when needed
+
+```bash
+# Get your key from https://aistudio.google.com/apikey
+export GEMINI_API_KEY="YOUR_API_KEY"
+qodercli
+```
+
+### Option 3: Vertex AI
+
+**✨ Best for:** Enterprise teams and production workloads
+
+**Benefits:**
+
+- **Enterprise features**: Advanced security and compliance
+- **Scalable**: Higher rate limits with billing account
+- **Integration**: Works with existing Google Cloud infrastructure
+
+```bash
+# Get your key from Google Cloud Console
+export GOOGLE_API_KEY="YOUR_API_KEY"
+export GOOGLE_GENAI_USE_VERTEXAI=true
+qodercli
+```
+
+For Google Workspace accounts and other authentication methods, see the
+[authentication guide](https://www.geminicli.com/docs/get-started/authentication).
+
+## 🚀 Getting Started
+
+### Basic Usage
+
+#### Start in current directory
+
+```bash
+qodercli
+```
+
+#### Include multiple directories
+
+```bash
+qodercli --include-directories ../lib,../docs
+```
+
+#### Use specific model
+
+```bash
+qodercli -m gemini-2.5-flash
+```
+
+#### Non-interactive mode for scripts
+
+Get a simple text response:
+
+```bash
+qodercli -p "Explain the architecture of this codebase"
+```
+
+For more advanced scripting, including how to parse JSON and handle errors, use
+the `--output-format json` flag to get structured output:
+
+```bash
+qodercli -p "Explain the architecture of this codebase" --output-format json
+```
+
+For real-time event streaming (useful for monitoring long-running operations),
+use `--output-format stream-json` to get newline-delimited JSON events:
+
+```bash
+qodercli -p "Run tests and deploy" --output-format stream-json
+```
+
+### Quick Examples
+
+#### Start a new project
+
+```bash
+cd new-project/
+qodercli
+> Write me a Discord bot that answers questions using a FAQ.md file I will provide
+```
+
+#### Analyze existing code
+
+```bash
+git clone <repository-url>
+cd qodercli
+qodercli
+> Give me a summary of all of the changes that went in yesterday
+```
+
+## 📚 Documentation
+
+### Getting Started
+
+- [**Quickstart Guide**](https://www.geminicli.com/docs/get-started) - Get up
+  and running quickly.
+- [**Authentication Setup**](https://www.geminicli.com/docs/get-started/authentication) -
+  Detailed auth configuration.
+- [**Configuration Guide**](https://www.geminicli.com/docs/reference/configuration) -
+  Settings and customization.
+- [**Keyboard Shortcuts**](https://www.geminicli.com/docs/reference/keyboard-shortcuts) -
+  Productivity tips.
+
+### Core Features
+
+- [**Commands Reference**](https://www.geminicli.com/docs/reference/commands) -
+  All slash commands (`/help`, `/chat`, etc).
+- [**Custom Commands**](https://www.geminicli.com/docs/cli/custom-commands) -
+  Create your own reusable commands.
+- [**Context Files (GEMINI.md)**](https://www.geminicli.com/docs/cli/gemini-md) -
+  Provide persistent context to Gemini CLI.
+- [**Checkpointing**](https://www.geminicli.com/docs/cli/checkpointing) - Save
+  and resume conversations.
+- [**Token Caching**](https://www.geminicli.com/docs/cli/token-caching) -
+  Optimize token usage.
+
+### Tools & Extensions
+
+- [**Built-in Tools Overview**](https://www.geminicli.com/docs/reference/tools)
+  - [File System Operations](https://www.geminicli.com/docs/tools/file-system)
+  - [Shell Commands](https://www.geminicli.com/docs/tools/shell)
+  - [Web Fetch & Search](https://www.geminicli.com/docs/tools/web-fetch)
+- [**MCP Server Integration**](https://www.geminicli.com/docs/tools/mcp-server) -
+  Extend with custom tools.
+- [**Custom Extensions**](https://geminicli.com/docs/extensions/writing-extensions) -
+  Build and share your own commands.
+
+### Advanced Topics
+
+- [**Headless Mode (Scripting)**](https://www.geminicli.com/docs/cli/headless) -
+  Use Gemini CLI in automated workflows.
+- [**IDE Integration**](https://www.geminicli.com/docs/ide-integration) - VS
+  Code companion.
+- [**Sandboxing & Security**](https://www.geminicli.com/docs/cli/sandbox) - Safe
+  execution environments.
+- [**Trusted Folders**](https://www.geminicli.com/docs/cli/trusted-folders) -
+  Control execution policies by folder.
+- [**Enterprise Guide**](https://www.geminicli.com/docs/cli/enterprise) - Deploy
+  and manage in a corporate environment.
+- [**Telemetry & Monitoring**](https://www.geminicli.com/docs/cli/telemetry) -
+  Usage tracking.
+- [**Tools reference**](https://www.geminicli.com/docs/reference/tools) -
+  Built-in tools overview.
+- [**Local development**](https://www.geminicli.com/docs/local-development) -
+  Local development tooling.
+
+### Troubleshooting & Support
+
+- [**Troubleshooting Guide**](https://www.geminicli.com/docs/resources/troubleshooting) -
+  Common issues and solutions.
+- [**FAQ**](https://www.geminicli.com/docs/resources/faq) - Frequently asked
+  questions.
+- Use `/bug` command to report issues directly from the CLI.
+
+### Using MCP Servers
+
+User-level settings live in `~/.qoder/settings.json` by default. Set
+`QODER_CONFIG_DIR` to use a different complete config root:
+
+```bash
+QODER_CONFIG_DIR=/tmp/qoder-dev qodercli
+```
+
+That example reads settings from `/tmp/qoder-dev/settings.json`; it does not
+append `.qoder` to the configured path.
+
+Configure MCP servers in the user settings file to extend Gemini CLI with custom
+tools:
+
+```text
+> @slack Send a summary of today's commits to #dev channel
+> @database Run a query to find inactive users
+```
+
+See the
+[MCP Server Integration guide](https://www.geminicli.com/docs/tools/mcp-server)
+for setup instructions.
+
+## 🤝 Contributing
+
+We welcome contributions! Gemini CLI is fully open source (Apache 2.0), and we
+encourage the community to:
+
+- Report bugs and suggest features.
+- Improve documentation.
+- Submit code improvements.
+- Share your MCP servers and extensions.
+
+See our [Contributing Guide](./CONTRIBUTING.md) for development setup, coding
+standards, and how to submit pull requests.
+
+## 📖 Resources
+
+- **[Official Roadmap](./ROADMAP.md)** - See what's coming next.
+- **[Changelog](https://www.geminicli.com/docs/changelogs)** - See recent
+  notable updates.
+- **[NPM Package](https://www.npmjs.com/package/@qoder-ai/qodercli)** - Package
+  registry.
+
+### Uninstall
+
+See the [Uninstall Guide](https://www.geminicli.com/docs/resources/uninstall)
+for removal instructions.
+
+## 📄 Legal
+
+- **License**: [Apache License 2.0](LICENSE)
+- **Terms of Service**:
+  [Terms & Privacy](https://www.geminicli.com/docs/resources/tos-privacy)
+- **Security**: [Security Policy](SECURITY.md)
 
 ---
+
+<p align="center">
+  Built with ❤️ by Google and the open source community
+</p>

package/bundle/builtin/agent-creator/SKILL.md

@@ -0,0 +1,327 @@
+---
+name: agent-creator
+description:
+  Guide for creating custom agents. Use when users want to create a new agent
+  that runs in an isolated context with custom system prompts and
+  specific tool access.
+allowed-tools: Edit, Write
+---
+
+# Creating Custom Agents for Qoder CLI
+
+This skill guides you through creating custom agents. Agents are
+specialized AI assistants that run in isolated contexts with custom system
+prompts, specific tool access, and independent permissions.
+
+## When to Use Agents
+
+Use agents when you need:
+
+- **Context isolation** for long research or exploration tasks
+- **Parallel execution** of multiple independent workstreams
+- **Specialized expertise** with custom prompts for specific domains
+- **Reusable configurations** across projects
+
+**When NOT to use agents:**
+
+- Simple, single-purpose tasks (use skills instead)
+- Tasks requiring frequent back-and-forth with the user
+- Quick, targeted changes
+
+## Agent Locations
+
+| Location                         | Scope             | Priority |
+| -------------------------------- | ----------------- | -------- |
+| `<project>/${QODER_CONFIG_DIR}/agents/` | Current project   | Higher   |
+| `~/${QODER_CONFIG_DIR}/agents/`         | All your projects | Lower    |
+
+**Project agents** (`${QODER_CONFIG_DIR}/agents/`): Ideal for codebase-specific
+agents. Check into version control to share with your team.
+
+**User agents** (`~/${QODER_CONFIG_DIR}/agents/`): Personal agents available across
+all your projects.
+
+## Agent File Format
+
+Each agent is a Markdown file with YAML frontmatter:
+
+```markdown
+---
+name: agent-name
+description: When to use this agent. Be specific!
+---
+
+You are a [role]. When invoked:
+
+1. [First step]
+2. [Second step]
+3. [Output format]
+```
+
+### Required Fields
+
+| Field         | Description                                                                |
+| ------------- | -------------------------------------------------------------------------- |
+| `name`        | Unique identifier (lowercase letters and hyphens only)                     |
+| `description` | When to delegate to this agent (be specific). Including trigger scenarios. |
+
+## Writing Effective Descriptions
+
+The description is **critical**. Include "use proactively" to encourage
+automatic delegation - Qoder CLI uses it to decide when to delegate.
+
+```yaml
+# Bad - Too vague
+description: Helps with code
+
+# Good - Specific and actionable
+description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
+```
+
+### Optional Fields
+
+| Field            | Description                                                                         |
+| ---------------- | ----------------------------------------------------------------------------------- |
+| `tools`          | Tools the agent can use (string or array)                                           |
+| `disallowedTools`| Tools to explicitly deny (string or array)                                          |
+| `model`          | Model to use: `inherit` (default), `sonnet`, `opus`, `haiku`                        |
+| `color`          | Display color: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan` |
+| `displayName`    | Human-friendly display name                                                         |
+| `maxTurns`       | Maximum conversation turns (positive integer)                                       |
+| `timeoutMins`    | Timeout in minutes (positive integer)                                               |
+| `effort`         | Thinking effort: `low`, `medium`, `high`, `max`                                     |
+| `skills`         | Skills the agent can use (string or array)                                          |
+
+#### Tools
+
+Specify which tools the agent has access to. This limits the agent's
+capabilities for security and focus.
+
+```yaml
+# Read-only access
+tools: Read, Grep, Glob
+
+# Full development access
+tools: Bash, Read, Write, Edit, Glob, Grep
+
+# Web research capabilities
+tools: Read, WebSearch, WebFetch
+```
+
+**Available Tools:**
+
+- `Bash` - Execute shell commands
+- `Read` - Read file contents
+- `Write` - Create new files
+- `Edit` - Modify existing files
+- `Glob` - Find files by pattern
+- `Grep` - Search file contents
+- `WebSearch` - Search the web
+- `WebFetch` - Fetch web page content
+
+If not specified, the agent inherits default tool access.
+
+## Agent Creation Workflow
+
+### Step 1: Decide the Scope
+
+If not sure where to create the agent, ask the user with two options:
+
+- **Project-level** (`.agents/`): For team-shared, codebase-specific agents
+- **User-level** (`~/.agents/`): For personal agents across all projects
+
+### Step 2: Gather Requirements
+
+Understand what the agent should do:
+
+- What specific task or domain?
+- What tools does it need?
+- Should it be read-only or have write access?
+- Any special constraints or workflows?
+
+### Step 3: Create the File
+
+```bash
+# For project-level
+mkdir -p ${QODER_CONFIG_DIR}/agents
+touch ${QODER_CONFIG_DIR}/agents/agent-name.md
+
+# For user-level
+mkdir -p ~/${QODER_CONFIG_DIR}/agents
+touch ~/${QODER_CONFIG_DIR}/agents/agent-name.md
+```
+
+### Step 4: Write Configuration
+
+Create the markdown file with:
+
+1. YAML frontmatter with required fields
+2. System prompt in the body
+
+### Step 5: Verify
+
+- Check file location is correct
+- Verify YAML syntax is valid
+- Confirm the description clearly describes when to use it
+- Tell the user: run `/agents reload` to make the new agent available in the
+  current session. They can then invoke it with:
+
+```
+@agent-name [task description]
+```
+
+## Best Practices
+
+1. **Design focused agents** - Each should excel at one specific task
+2. **Write detailed descriptions** - Be detailed and specific so Qoder CLI knows
+   when to delegate
+3. **Limit tool access** - Grant only necessary permissions for security and
+   focus
+4. **Keep prompts concise** - Long, rambling prompts dilute focus
+
+## Anti-Patterns to Avoid
+
+- **Vague descriptions** - "Use for general tasks" gives no signal
+- **Overly long prompts** - A 2000-word prompt doesn't make it smarter
+
+## Examples
+
+### Verifier
+
+```markdown
+---
+name: verifier
+description:
+  Validates completed work. Use after tasks are marked done to confirm
+  implementations are functional.
+color: yellow
+---
+
+You are a skeptical validator. Your job is to verify that work claimed as
+complete actually works.
+
+When invoked:
+
+1. Identify what was claimed to be completed
+2. Check that the implementation exists and is functional
+3. Run relevant tests or verification steps
+4. Look for edge cases that may have been missed
+
+Be thorough and skeptical. Report:
+
+- What was verified and passed
+- What was claimed but incomplete or broken
+- Specific issues that need to be addressed
+
+Do not accept claims at face value. Test everything.
+```
+
+### Debugger
+
+```markdown
+---
+name: debugger
+description:
+  Debugging specialist for errors and test failures. Use when encountering
+  issues.
+color: red
+---
+
+You are an expert debugger specializing in root cause analysis.
+
+When invoked:
+
+1. Capture error message and stack trace
+2. Identify reproduction steps
+3. Isolate the failure location
+4. Implement minimal fix
+5. Verify solution works
+
+For each issue, provide:
+
+- Root cause explanation
+- Evidence supporting the diagnosis
+- Specific code fix
+- Testing approach
+
+Focus on fixing the underlying issue, not symptoms.
+```
+
+### Data Scientist
+
+```markdown
+---
+name: data-scientist
+description:
+  Data analysis expert for SQL queries, BigQuery operations, and data insights.
+  Use proactively for data analysis tasks and queries.
+tools: Bash, Read, Write
+---
+
+You are a data scientist specializing in SQL and BigQuery analysis.
+
+When invoked:
+
+1. Understand the data analysis requirement
+2. Write efficient SQL queries
+3. Use BigQuery command line tools (bq) when appropriate
+4. Analyze and summarize results
+5. Present findings clearly
+
+Key practices:
+
+- Write optimized SQL queries with proper filters
+- Use appropriate aggregations and joins
+- Include comments explaining complex logic
+- Format results for readability
+- Provide data-driven recommendations
+
+For each analysis:
+
+- Explain the query approach
+- Document any assumptions
+- Highlight key findings
+- Suggest next steps based on data
+
+Always ensure queries are efficient and cost-effective.
+```
+
+### Security Auditor
+
+```markdown
+---
+name: security-auditor
+description:
+  Security specialist. Use when implementing auth, payments, or handling
+  sensitive data. Proactively audit security-sensitive code.
+tools: Read, Grep, Glob
+color: red
+model: sonnet
+---
+
+You are a security expert auditing code for vulnerabilities.
+
+When invoked:
+
+1. Identify security-sensitive code paths
+2. Check for common vulnerabilities (injection, XSS, auth bypass)
+3. Verify secrets are not hardcoded
+4. Review input validation and sanitization
+
+Report findings by severity:
+
+- Critical (must fix before deploy)
+- High (fix soon)
+- Medium (address when possible)
+
+Security checklist:
+
+- SQL injection prevention
+- XSS protection
+- CSRF tokens
+- Authentication bypass risks
+- Authorization checks
+- Secret management
+- Input validation
+- Output encoding
+```