---
url: /kirox/config/kiroxrc.md
description: Kirox CLI configuration file reference
---

# .kiroxrc.json

Reference for the Kirox CLI configuration file.

## Overview

`.kiroxrc.json` is a configuration file that defines default behavior for Kirox CLI. By placing it in the project root, you can omit settings when executing commands.

## File Format

**Format**: JSON
**Location**: Project root
**Filename**: `.kiroxrc.json`

## Configuration Options

### defaultRepository

Specifies the default GitHub repository.

**Type**: `string`
**Format**: `owner/repo`
**Default**: None (not set)

**Example**:

```json
{
  "defaultRepository": "yukihirop/my-project"
}
```

**Behavior**: Used when the repository argument is omitted.

```bash
# With defaultRepository set
npx kirox -p api-spec
# => Fetches api-spec from yukihirop/my-project

# Without defaultRepository set
npx kirox -p api-spec
# => Error: Please specify repository
```

### defaultProjects

Specifies the default project list.

**Type**: `string[]`
**Default**: None (not set)

**Example**:

```json
{
  "defaultProjects": ["api-spec", "web-spec", "mobile-spec"]
}
```

**Behavior**: Used when the `--project` option is omitted.

```bash
# With defaultProjects set
npx kirox yukihirop/my-project
# => Fetches api-spec, web-spec, mobile-spec

# Without defaultProjects set
npx kirox yukihirop/my-project
# => Interactive mode for project selection
```

### force

Skips overwrite confirmation for existing files.

**Type**: `boolean`
**Default**: `false`

**Example**:

```json
{
  "force": true
}
```

**Behavior**:

* `true`: Overwrite existing files without confirmation
* `false`: Display confirmation prompt if existing files exist

::: warning Warning
`force: true` overwrites existing files without warning. Use with caution in production environments.
:::

### verbose

Displays detailed logs.

**Type**: `boolean`
**Default**: `false`

**Example**:

```json
{
  "verbose": true
}
```

**Behavior**:

* `true`: Display detailed logs
* `false`: Display normal logs only

**Log Example**:

```
[DEBUG] Loading config from .kiroxrc.json
[DEBUG] Fetching repository: yukihirop/my-project
[DEBUG] Branch: main
[INFO] Fetching .kiro/specs/api-spec/requirements.md...
```

### track

Enables update tracking.

**Type**: `boolean`
**Default**: `false`

**Example**:

```json
{
  "track": true
}
```

**Behavior**:

* `true`: Track remote repository changes and fetch only changed files
* `false`: Fetch all files every time

## Complete Configuration Examples

### Basic Configuration

```json
{
  "defaultRepository": "yukihirop/my-project",
  "defaultProjects": ["api-spec"],
  "force": false,
  "verbose": false,
  "track": false
}
```

### Team Development Configuration

Automatically fetch multiple projects and enable update tracking:

```json
{
  "defaultRepository": "company/shared-specs",
  "defaultProjects": ["backend-api", "frontend-web", "mobile-app"],
  "force": false,
  "verbose": true,
  "track": true
}
```

### CI/CD Configuration

Enable force overwrite and detailed logging:

```json
{
  "defaultRepository": "company/project",
  "defaultProjects": ["api-spec"],
  "force": true,
  "verbose": true,
  "track": false
}
```

### Personal Development Configuration

Simple configuration with force overwrite:

```json
{
  "defaultRepository": "username/my-project",
  "defaultProjects": ["main-spec"],
  "force": true,
  "verbose": false,
  "track": false
}
```

## Configuration Priority

Configuration is applied in the following priority order (higher takes precedence):

1. **Command-line options**
   ```bash
   npx kirox owner/repo -p project --force --verbose
   ```

2. **`.kiroxrc.json` configuration file**
   ```json
   { "force": false, "verbose": false }
   ```

3. **Environment variables**
   ```bash
   export GITHUB_TOKEN=ghp_...
   ```

4. **Default values**
   ```typescript
   { force: false, verbose: false, track: false }
   ```

## Custom Configuration File

To use a configuration file other than the default `.kiroxrc.json`:

```bash
npx kirox owner/repo -p project --config custom-config.json
```

**Custom configuration file example** (`team-config.json`):

```json
{
  "defaultRepository": "company/team-repo",
  "defaultProjects": ["team-spec"],
  "force": false,
  "verbose": true,
  "track": true
}
```

## Configuration File Validation

To verify the configuration file format is correct, run with the `--verbose` option:

```bash
npx kirox owner/repo -p project --verbose
```

**Sample Output**:

```
[DEBUG] Loading config from .kiroxrc.json
[DEBUG] Config loaded: { defaultRepository: 'yukihirop/my-project', ... }
```

## Troubleshooting

### Configuration File Not Loading

**Cause**: Filename spelling error or JSON format error

**Solution**:

1. Verify filename (`.kiroxrc.json`)
2. Validate JSON format:
   ```bash
   cat .kiroxrc.json | jq .
   ```

### Configuration Not Applied

**Cause**: Command-line options override configuration file

**Solution**:

1. Verify command-line options
2. Check configuration with `--verbose` option

### JSON Syntax Error

**Error Message**:

```
Error: Invalid JSON in .kiroxrc.json
```

**Solution**:

1. Validate with JSON linter
2. Check commas, brackets, quotes

## Best Practices

### Team Development

* Include `.kiroxrc.json` in version control
* Use common configuration across team
* Define project-specific settings

```json
{
  "defaultRepository": "company/shared-specs",
  "defaultProjects": ["backend-api", "frontend-web"],
  "track": true
}
```

### Personal Development

* Add `.kiroxrc.json` to `.gitignore` (for personal settings)
* Configure frequently used repositories and projects

```json
{
  "defaultRepository": "username/my-project",
  "defaultProjects": ["main-spec"],
  "force": true
}
```

### CI/CD Environment

* Enable force overwrite and detailed logging
* Disable update tracking (fetch clean state every time)

```json
{
  "force": true,
  "verbose": true,
  "track": false
}
```

## Related Pages

* [Configuration Guide](/config/): Configuration overview
* [Advanced Usage](/guide/advanced-usage): How to utilize configuration files
* [CLI Reference](/cli/): Details on commands and options

---

---
url: /kirox/cli/add.md
description: Subcommand to add projects
---

# add Command

Adds new projects to existing local projects.

## Syntax

```bash
npx kirox add [<owner/repo>[#branch]] [options]
```

## Overview

The `add` subcommand adds new projects to an existing `.kiro/` directory. The difference from the main command (`kirox`) is that it preserves existing steering files.

**Key Differences**:

* **`kirox`**: Fetches everything including steering files
* **`add`**: Adds only specified projects and preserves existing steering

## Arguments

### `<owner/repo>[#branch]`

Specify a GitHub repository (optional).

**Format**:

* `owner/repo`: Specify repository only (uses default branch)
* `owner/repo#branch`: Specify branch as well

**Examples**:

```bash
npx kirox add yukihirop/my-project -p new-project
npx kirox add yukihirop/my-project#develop -p new-project
```

**When omitted**: Interactive mode prompts for input

## Options

The `add` command supports the same options as the `kirox` command (except `--steering`).

### `-p, --project <projects>`

Specify project name(s) to add (comma-separated for multiple).

**Type**: `string`

**Examples**:

```bash
# Add single project
npx kirox add yukihirop/my-project -p new-project

# Add multiple projects
npx kirox add yukihirop/my-project -p project1,project2
```

### `-f, --force`

Overwrite existing files without confirmation.

**Type**: `boolean`
**Default**: `false`

**Example**:

```bash
npx kirox add yukihirop/my-project -p new-project --force
```

### `--dry-run`

Simulate file writing and display which files would be added.

**Type**: `boolean`
**Default**: `false`

**Example**:

```bash
npx kirox add yukihirop/my-project -p new-project --dry-run
```

### `--verbose`

Display detailed logs.

**Type**: `boolean`
**Default**: `false`

**Example**:

```bash
npx kirox add yukihirop/my-project -p new-project --verbose
```

### `--track`

Track changes in remote repository.

**Type**: `boolean`
**Default**: `false`

**Example**:

```bash
npx kirox add yukihirop/my-project -p new-project --track
```

### `--subdirectory <path>`

Fetch `.kiro/` files from a subdirectory within the repository.

**Type**: `string`

**Example**:

```bash
npx kirox add yukihirop/monorepo -p new-project --subdirectory backend
```

### `-c, --config <path>`

Specify configuration file path.

**Type**: `string`
**Default**: `.kiroxrc.json`

**Example**:

```bash
npx kirox add yukihirop/my-project -p new-project --config custom-config.json
```

### `-h, --help`

Display help message.

**Example**:

```bash
npx kirox add --help
```

## Interactive Mode

Run without arguments and options to configure interactively.

```bash
npx kirox add
```

**Prompts**:

1. **Repository input**: Enter in `owner/repo` format
2. **Branch selection**: Select from available branches with searchable checkbox (optional)
3. **Subdirectory selection**: Select from detected subdirectories (optional)
4. **Project selection**: Select from available projects with searchable checkbox (multiple selection available)

## Usage Examples

### Basic Usage

Add new project to existing local project:

```bash
# Current state
.kiro/
├── specs/
│   └── api-spec/
└── steering/

# Add new project
npx kirox add yukihirop/my-project -p web-spec

# After addition
.kiro/
├── specs/
│   ├── api-spec/     # Existing
│   └── web-spec/     # Newly added
└── steering/         # Unchanged
```

### Add Multiple Projects

```bash
npx kirox add yukihirop/my-project -p mobile-spec,infra-spec
```

### Add with Branch Specification

```bash
npx kirox add yukihirop/my-project#develop -p new-project
```

### Add from Subdirectory

```bash
npx kirox add yukihirop/monorepo -p new-project --subdirectory frontend
```

### Add in Interactive Mode

```bash
$ npx kirox add

? Enter repository: yukihirop/my-project
? Select branch (searchable): main
? Select subdirectory: (skip)
? Select projects (searchable, multiple selection):
  ☑ web-spec
  ☑ mobile-spec
  ☐ infra-spec
```

## Comparison with kirox Command

| Feature | `kirox` | `kirox add` |
|------|---------|-------------|
| Fetch steering | ✓ | ✗ |
| Add projects | ✓ | ✓ |
| Preserve existing steering | ✗ | ✓ |
| Use case | Initial setup | Fetch additional projects |

## Execution Flow

1. **Check existing `.kiro/` directory**: Warns if it doesn't exist
2. **Load configuration**: `.kiroxrc.json` or custom config file
3. **GitHub API authentication**: `GITHUB_TOKEN` environment variable (optional)
4. **Fetch repository information**: Branch, subdirectory, project list
5. **Fetch project files**: Fetch only specified projects
6. **Write files**: Save to local `.kiro/specs/`
7. **Display summary**: Show success/failure file counts

::: tip Tip
If the `.kiro/` directory doesn't exist, first perform initial setup with the `kirox` command.
:::

## Exit Codes

| Code | Description |
|-------|------|
| `0` | Success |
| `1` | Argument error |
| `2` | GitHub API error |
| `3` | Filesystem error |
| `4` | Configuration error |

## Related Pages

* [kirox command](/cli/kirox): Details on main command
* [Basic Usage](/guide/basic-usage): Basic command usage
* [Advanced Usage](/guide/advanced-usage): Configuration files, branch specification, subdirectory support

---

---
url: /kirox/guide/advanced-usage.md
description: Advanced features and configuration for Kirox CLI
---

# Advanced Usage

This guide explains the advanced features and configuration of Kirox CLI.

## Configuration File (.kiroxrc.json)

You can customize default settings by placing a `.kiroxrc.json` file in your project root.

### Creating a Configuration File

```json
{
  "defaultRepository": "yukihirop/my-project",
  "defaultProjects": ["api-spec", "web-spec"],
  "force": false,
  "verbose": false,
  "track": false
}
```

### Configuration Options

| Option | Type | Description |
|------|------|------|
| `defaultRepository` | `string` | Default repository (`owner/repo` format) |
| `defaultProjects` | `string[]` | List of default projects |
| `force` | `boolean` | Skip overwrite confirmation (default: `false`) |
| `verbose` | `boolean` | Display verbose logs (default: `false`) |
| `track` | `boolean` | Enable update tracking (default: `false`) |

### Priority Order

Configuration priority is as follows (higher takes precedence):

1. Command-line options
2. `.kiroxrc.json` configuration file
3. Environment variables
4. Default values

## Branch Specification

You can specify a repository branch to fetch files from.

### Branch Specification Syntax

```bash
npx kirox owner/repo#branch -p project-name
```

### Examples

```bash
# Fetch from develop branch
npx kirox yukihirop/my-project#develop -p api-spec

# Fetch from feature/new-feature branch
npx kirox yukihirop/my-project#feature/new-feature -p api-spec
```

### Branch Selection in Interactive Mode

In interactive mode, you can select from available branches with a searchable checkbox:

```bash
$ npx kirox

? Enter repository: yukihirop/my-project
? Select branch (searchable):
  ❯ ◯ main
    ◯ develop
    ◯ feature/new-feature
```

## Subdirectory Support

You can fetch `.kiro` files from subdirectories within a repository.

### Specifying a Subdirectory

```bash
npx kirox owner/repo -p project-name --subdirectory path/to/subdir
```

### Examples

```bash
# Fetch from backend directory in monorepo
npx kirox yukihirop/monorepo -p api-spec --subdirectory backend

# Fetch from both frontend and backend
npx kirox yukihirop/monorepo -p web-spec --subdirectory frontend
npx kirox yukihirop/monorepo -p api-spec --subdirectory backend
```

### Subdirectory Selection in Interactive Mode

In interactive mode, detected subdirectories are automatically suggested:

```bash
$ npx kirox

? Enter repository: yukihirop/monorepo
? Select subdirectory:
  ❯ ◯ backend
    ◯ frontend
    ◯ packages/core
```

## Managing Multiple Projects

### add Subcommand

Add new projects to an existing local project:

```bash
npx kirox add owner/repo -p new-project
```

Also available in interactive mode:

```bash
npx kirox add
```

### Project Suggestion Feature

In interactive mode, available projects in the repository are automatically detected and suggested:

```bash
$ npx kirox

? Enter repository: yukihirop/my-project
? Select projects (searchable, multiple selection):
  ❯ ☑ api-spec
    ☑ web-spec
    ☐ mobile-spec
    ☐ infra-spec
```

## Shell Completion

Support for shell completion in bash, zsh, fish, PowerShell, and elvish.

### Generating Completion Scripts

```bash
# bash
npx kirox completion bash > /etc/bash_completion.d/kirox

# zsh
npx kirox completion zsh > ~/.zsh/completion/_kirox

# fish
npx kirox completion fish > ~/.config/fish/completions/kirox.fish

# PowerShell
npx kirox completion powershell > kirox.ps1

# elvish
npx kirox completion elvish > ~/.elvish/lib/kirox.elv
```

### Enabling Completion

```bash
# bash
source /etc/bash_completion.d/kirox

# zsh (after running compinit)
source ~/.zsh/completion/_kirox

# fish
# Automatically loaded
```

## Environment Variables

### GITHUB\_TOKEN

Used for GitHub API authentication:

```bash
export GITHUB_TOKEN=ghp_your_token_here
```

Required for accessing private repositories or relaxing rate limits.

### NODE\_ENV

Specify the execution environment:

```bash
export NODE_ENV=development  # or production, test
```

### DEBUG

Enable debug logging:

```bash
export DEBUG=kirox:*
npx kirox owner/repo -p project-name
```

## Performance Optimization

### Parallel File Fetching

Kirox CLI fetches up to 5 files in parallel. This achieves approximately 80% time reduction when fetching large numbers of files.

### Rate Limit Handling

Automatically detects and responds to GitHub API rate limits:

* **Without authentication**: 60 requests/hour
* **With authentication**: 5,000 requests/hour

When fetching large numbers of files, it is recommended to set `GITHUB_TOKEN`.

## Next Steps

* [Troubleshooting](/guide/troubleshooting): Common issues and solutions
* [Configuration Reference](/config/kiroxrc): Detailed .kiroxrc.json configuration
* [API Specification](/api/): Kirox CLI API specification

---

---
url: /kirox/api.md
description: Kirox CLI API specification
---

# API Specification

API specification for Kirox CLI's major modules.

## Architecture Overview

Kirox CLI adopts a Layer-Based Architecture:

```
CLI Layer (src/cli/)
    ↓
GitHub Integration Layer (src/github/)
    ↓
File System Layer (src/filesystem/)
    ↓
Reporting Layer (src/reporting/)
```

## Major Modules

### [GitHub Fetcher](/api/github-fetcher)

Module for fetching files from GitHub repositories.

**Responsibilities**:

* Communication with GitHub API
* Fetching repository content
* Decoding base64-encoded content
* Parallel file fetching and semaphore control
* Rate limit monitoring and handling

### [FileSystem Writer](/api/filesystem-writer)

Module for writing files to the local filesystem.

**Responsibilities**:

* Writing to local filesystem
* Automatic directory creation
* Existing file overwrite confirmation prompt
* \--dry-run mode processing

## Architecture Principles

### 1. Single Responsibility Principle (SRP)

Each component has a single responsibility.

### 2. Dependency Inversion Principle (DIP)

Upper layers depend on abstractions (interfaces), not on concrete implementations.

### 3. Layer Isolation

Minimize direct dependencies between layers; GitHub and FileSystem layers don't depend on each other.

## Development Guidelines

### TypeScript

* **Strict type checking**: `strict: true`
* **No `any`**: Enforce explicit type definitions
* **Explicit return types**: Explicitly specify function return types instead of relying on inference

### Naming

* **Functions**: Camel case starting with verbs (`fetchFiles`, `validateInput`)
* **Classes**: Noun-based Pascal case (`GitHubFetcher`, `ProgressReporter`)
* **Constants**: Upper snake case (`MAX_CONCURRENCY`, `DEFAULT_CONFIG`)

### Error Handling

* **Custom error classes**: Define domain-specific error types
* **Proper error propagation**: Don't suppress errors with try-catch

### Async/Await

* **No Promise chains**: Prefer async/await
* **Parallel processing**: Use `Promise.all()` / `Promise.allSettled()`

## Performance

* **Parallel file fetching**: Max 5 concurrent
* **Large file fetching**: Within 30 seconds for 50 files
* **Memory usage**: Within 100MB for 100 files
* **Rate limit avoidance**: No GitHub API rate limit violation for 100 files

## Next Steps

* [GitHub Fetcher API](/api/github-fetcher): Details on GitHub integration
* [FileSystem Writer API](/api/filesystem-writer): Details on filesystem operations

---

---
url: /kirox/guide/basic-usage.md
description: Basic commands and options for Kirox CLI
---

# Basic Usage

This guide explains the basic commands and options of Kirox CLI.

## Basic Commands

### Fetch Files from Repository

```bash
npx kirox <owner/repo> -p <project-name>
```

**Example**:

```bash
npx kirox yukihirop/my-project -p my-spec
```

This will fetch:

* All files under `.kiro/specs/my-spec/`
* All files under `.kiro/steering/`

### Interactive Mode

Running without options allows interactive configuration:

```bash
npx kirox
```

## Main Options

### Project Specification (`-p, --project`)

Specify the project(s) to fetch:

```bash
# Single project
npx kirox owner/repo -p project1

# Multiple projects (comma-separated)
npx kirox owner/repo -p project1,project2,project3
```

### Update Tracking (`--track`)

Track changes in the remote repository:

```bash
npx kirox owner/repo -p project1 --track
```

Default is `false`. When `--track` is specified, only changed files will be fetched on subsequent runs.

### Fetch Steering Only (`--steering`)

Fetch only `.kiro/steering/` and skip project specifications:

```bash
npx kirox owner/repo --steering
```

### Skip Overwrite Confirmation (`-f, --force`)

Overwrite existing files without confirmation:

```bash
npx kirox owner/repo -p project1 --force
```

::: warning Warning
The `--force` option overwrites existing files without warning. Use with caution.
:::

### Dry Run (`--dry-run`)

Preview which files would be fetched without actually writing them:

```bash
npx kirox owner/repo -p project1 --dry-run
```

### Verbose Logging (`--verbose`)

Display detailed logs:

```bash
npx kirox owner/repo -p project1 --verbose
```

## Usage Examples

### Basic Fetch

```bash
$ npx kirox yukihirop/my-project -p api-spec

✓ Fetching files from yukihirop/my-project...
✓ [1/5] requirements.md
✓ [2/5] design.md
✓ [3/5] tasks.md
✓ [4/5] spec.json
✓ [5/5] steering/tech.md

Summary:
  Succeeded: 5 files
  Failed: 0 files
```

### Fetch Multiple Projects

```bash
$ npx kirox yukihirop/my-project -p api-spec,web-spec

✓ Fetching files from yukihirop/my-project...
✓ Project: api-spec (5 files)
✓ Project: web-spec (4 files)

Summary:
  Succeeded: 9 files
  Failed: 0 files
```

### Preview with Dry Run

```bash
$ npx kirox yukihirop/my-project -p api-spec --dry-run

[DRY RUN] The following files would be fetched:
  .kiro/specs/api-spec/requirements.md
  .kiro/specs/api-spec/design.md
  .kiro/specs/api-spec/tasks.md
  .kiro/specs/api-spec/spec.json
  .kiro/steering/tech.md

No files were written (dry run mode).
```

## Display Help

Display command help:

```bash
npx kirox --help
```

Display subcommand help:

```bash
npx kirox add --help
npx kirox completion --help
```

## Next Steps

* [Advanced Usage](/guide/advanced-usage): Configuration files, branch specification, subdirectory support
* [CLI Reference](/cli/): Details on all commands and options
* [Troubleshooting](/guide/troubleshooting): Common issues and solutions

---

---
url: /kirox/cli.md
description: Reference for Kirox CLI commands
---

# CLI Reference

Reference for all Kirox CLI commands and options.

## Command List

### [kirox](/cli/kirox)

Main command. Fetches `.kiro/` files from GitHub repositories.

```bash
npx kirox <owner/repo> [options]
```

### [add](/cli/add)

Adds new projects to existing local projects.

```bash
npx kirox add <owner/repo> [options]
```

### [completion](/cli/completion)

Outputs shell completion scripts.

```bash
npx kirox completion <shell>
```

## Global Options

Options available for all commands:

| Option | Short | Description |
|-----------|--------|------|
| `--help` | `-h` | Display help |
| `--version` | `-V` | Display version |

## Common Options

Options available for `kirox` and `add` commands:

| Option | Short | Type | Description |
|-----------|--------|------|------|
| `--project` | `-p` | `string` | Project name(s) (comma-separated for multiple) |
| `--force` | `-f` | `boolean` | Skip overwrite confirmation |
| `--dry-run` | | `boolean` | Simulate file writing |
| `--verbose` | | `boolean` | Display detailed logs |
| `--track` | | `boolean` | Enable update tracking |
| `--steering` | | `boolean` | Fetch steering only |
| `--subdirectory` | | `string` | Subdirectory path |
| `--config` | `-c` | `string` | Configuration file path |

## Usage Examples

### Basic Usage

```bash
# Fetch specific project
npx kirox yukihirop/my-project -p api-spec

# Interactive mode
npx kirox

# Display help
npx kirox --help
```

### With Options

```bash
# Fetch multiple projects
npx kirox yukihirop/my-project -p api-spec,web-spec

# Specify branch
npx kirox yukihirop/my-project#develop -p api-spec

# No confirmation
npx kirox yukihirop/my-project -p api-spec --force

# Dry run
npx kirox yukihirop/my-project -p api-spec --dry-run

# Verbose logs
npx kirox yukihirop/my-project -p api-spec --verbose
```

### Subcommands

```bash
# Add project
npx kirox add yukihirop/my-project -p new-project

# Generate shell completion scripts
npx kirox completion bash > /etc/bash_completion.d/kirox
npx kirox completion zsh > ~/.zsh/completion/_kirox
npx kirox completion fish > ~/.config/fish/completions/kirox.fish
```

## Next Steps

* [kirox command](/cli/kirox): Details on main command
* [add command](/cli/add): Details on add subcommand
* [completion command](/cli/completion): Details on completion subcommand

---

---
url: /kirox/cli/completion.md
description: Shell completion script generation command
---

# completion Command

Outputs shell completion scripts. Supports bash, zsh, fish, PowerShell, and elvish.

## Syntax

```bash
npx kirox completion <shell>
```

## Arguments

### `<shell>`

Specify the shell type (required).

**Supported Shells**:

* `bash`
* `zsh`
* `fish`
* `powershell`
* `elvish`

## Usage

### bash

```bash
# Generate completion script
npx kirox completion bash > /etc/bash_completion.d/kirox

# Or place in user directory
npx kirox completion bash > ~/.bash_completion.d/kirox

# Enable
source /etc/bash_completion.d/kirox
# or
source ~/.bash_completion.d/kirox
```

**Persistence**: Add to `.bashrc`

```bash
if [ -f ~/.bash_completion.d/kirox ]; then
  source ~/.bash_completion.d/kirox
fi
```

### zsh

```bash
# Generate completion script
npx kirox completion zsh > ~/.zsh/completion/_kirox

# Add completion directory to fpath before compinit
# Add to .zshrc
fpath=(~/.zsh/completion $fpath)
autoload -Uz compinit && compinit
```

**With Oh My Zsh**:

```bash
# Place in Oh My Zsh custom plugin directory
mkdir -p ~/.oh-my-zsh/custom/plugins/kirox
npx kirox completion zsh > ~/.oh-my-zsh/custom/plugins/kirox/_kirox

# Add to plugins in .zshrc
plugins=(... kirox)
```

### fish

```bash
# Generate completion script
npx kirox completion fish > ~/.config/fish/completions/kirox.fish

# fish automatically loads completions
# Restart shell or run
source ~/.config/fish/completions/kirox.fish
```

### PowerShell

```bash
# Generate completion script
npx kirox completion powershell > kirox.ps1

# Add to profile
# Check profile path
echo $PROFILE

# Add completion script to profile
Add-Content $PROFILE ". path\to\kirox.ps1"

# Or write directly to profile
npx kirox completion powershell >> $PROFILE
```

### elvish

```bash
# Generate completion script
npx kirox completion elvish > ~/.elvish/lib/kirox.elv

# Add to rc.elv
use kirox
```

## Completion Content

Shell completion auto-completes the following:

### Commands

* `kirox`
* `add`
* `completion`

### Options

* `--project`, `-p`
* `--force`, `-f`
* `--dry-run`
* `--verbose`
* `--track`
* `--steering`
* `--subdirectory`
* `--config`, `-c`
* `--help`, `-h`
* `--version`, `-V`

### Shell Names (completion command)

* `bash`
* `zsh`
* `fish`
* `powershell`
* `elvish`

## Usage Examples

### Testing Completion

When completion is properly configured, it works as follows:

```bash
# Command completion
$ npx kirox [TAB]
add        completion

# Option completion
$ npx kirox --[TAB]
--project      --force        --dry-run
--verbose      --track        --steering
--subdirectory --config       --help
--version

# Shell name completion
$ npx kirox completion [TAB]
bash       zsh        fish
powershell elvish
```

## Troubleshooting

### Completion Not Working (bash)

**Check**:

1. Verify bash-completion is installed

```bash
# macOS (Homebrew)
brew install bash-completion

# Ubuntu/Debian
apt-get install bash-completion
```

2. Verify bash-completion is enabled (add to `.bashrc`)

```bash
if [ -f /etc/bash_completion ]; then
  . /etc/bash_completion
fi
```

3. Restart shell

```bash
exec bash
```

### Completion Not Working (zsh)

**Check**:

1. Verify compinit is executed (add to `.zshrc`)

```bash
autoload -Uz compinit && compinit
```

2. Verify completion directory is in fpath

```bash
echo $fpath
```

3. Reset completion cache

```bash
rm ~/.zcompdump*
exec zsh
```

### Completion Not Working (fish)

**Check**:

1. Verify completion file path is correct

```bash
ls ~/.config/fish/completions/kirox.fish
```

2. Restart fish

```bash
exec fish
```

## Manual Completion Setup

If automatic completion script generation doesn't work, you can set it up manually.

### bash (manual)

```bash
# Add to .bashrc
_kirox_completion() {
  local cur="${COMP_WORDS[COMP_CWORD]}"
  local prev="${COMP_WORDS[COMP_CWORD-1]}"

  case "${prev}" in
    kirox)
      COMPREPLY=( $(compgen -W "add completion --project --force --dry-run --verbose --track --steering --subdirectory --config --help --version" -- ${cur}) )
      return 0
      ;;
    completion)
      COMPREPLY=( $(compgen -W "bash zsh fish powershell elvish" -- ${cur}) )
      return 0
      ;;
  esac
}

complete -F _kirox_completion kirox
```

## Related Pages

* [kirox command](/cli/kirox): Details on main command
* [add command](/cli/add): Details on add subcommand
* [Getting Started](/guide/getting-started): Installation and initial setup

---

---
url: /kirox/config.md
description: Kirox CLI configuration guide
---

# Configuration

This guide explains how to configure Kirox CLI.

## Configuration File

Kirox CLI can customize its behavior with a `.kiroxrc.json` file placed in the project root.

### [.kiroxrc.json](/config/kiroxrc)

Configuration file that defines project default settings.

**Location**: Project root

**Example**:

```json
{
  "defaultRepository": "yukihirop/my-project",
  "defaultProjects": ["api-spec", "web-spec"],
  "force": false,
  "verbose": false,
  "track": false
}
```

## Configuration Priority

Configuration is applied in the following priority order (higher takes precedence):

1. **Command-line options**: Options specified at runtime
2. **Configuration file**: `.kiroxrc.json` contents
3. **Environment variables**: `GITHUB_TOKEN`, etc.
4. **Default values**: Built-in default values

## Environment Variables

### GITHUB\_TOKEN

Used for GitHub API authentication.

```bash
export GITHUB_TOKEN=ghp_your_token_here
```

**Purpose**:

* Access to private repositories
* Relax rate limits (60 → 5,000 requests/hour)

**How to Obtain**:

1. Go to [GitHub Settings → Developer settings → Personal access tokens](https://github.com/settings/tokens)
2. Click "Generate new token (classic)"
3. Select the following scopes:
   * `public_repo`: Read public repositories
   * `repo`: Read private repositories (if needed)

### NODE\_ENV

Specifies the execution environment.

```bash
export NODE_ENV=development  # or production, test
```

**Effects**: Log level, error verbosity

### DEBUG

Enables debug logging.

```bash
export DEBUG=kirox:*
npx kirox owner/repo -p project-name
```

## Custom Configuration File

To use a configuration file other than the default `.kiroxrc.json`, specify it with the `--config` option.

```bash
npx kirox owner/repo -p project --config custom-config.json
```

## Configuration Examples

### Team Development Configuration

Configure repository shared across team:

```json
{
  "defaultRepository": "company/shared-specs",
  "defaultProjects": ["backend-api", "frontend-web"],
  "track": true,
  "verbose": false
}
```

### Personal Development Configuration

Configuration for personal projects:

```json
{
  "defaultRepository": "username/my-project",
  "defaultProjects": ["main-spec"],
  "force": true,
  "track": false
}
```

### CI/CD Environment Configuration

Configuration for CI/CD environments:

```json
{
  "defaultRepository": "company/project",
  "defaultProjects": ["api-spec"],
  "force": true,
  "verbose": true,
  "track": false
}
```

## Next Steps

* [.kiroxrc.json Reference](/config/kiroxrc): Details on configuration options
* [Advanced Usage](/guide/advanced-usage): How to utilize configuration files

---

---
url: /kirox/api/filesystem-writer.md
description: Filesystem operations module API specification
---

# FileSystem Writer API

API specification for the module that writes files to the local filesystem.

## Overview

FileSystem Writer (`src/filesystem/`) is the layer responsible for writing to the local filesystem.

**Key Features**:

* Writing to local filesystem
* Automatic directory creation (`.kiro/specs/`, `.kiro/steering/`)
* Existing file overwrite confirmation prompt
* \--dry-run mode processing (skip writing)

## Directory Structure

```
src/filesystem/
├── writer.ts          # FileWriter: Main file writing logic
├── prompt.ts          # PromptService: Interactive prompts (overwrite confirmation)
├── path-utils.ts      # Path conversion utilities (remote→local)
└── types.ts           # Filesystem layer type definitions (WriteOptions, etc.)
```

## Main Classes and Interfaces

### FileWriter

Main class for writing files.

#### Constructor

```typescript
class FileWriter {
  constructor(private options: WriterOptions) {}
}
```

**Parameters**:

* `options`: Writer options

#### Methods

##### writeFiles()

Writes multiple files to the local filesystem.

```typescript
async writeFiles(
  files: FileContent[],
  options?: WriteOptions
): Promise<WriteResult[]>
```

**Parameters**:

* `files`: Array of files to write
* `options`: Write options (optional)

**Return Value**: `WriteResult[]` - Array of write results

**Example**:

```typescript
const writer = new FileWriter({ force: false, dryRun: false });
const results = await writer.writeFiles([
  { path: '.kiro/specs/api-spec/requirements.md', content: '...' },
  { path: '.kiro/steering/tech.md', content: '...' }
]);
```

##### writeFile()

Writes a single file.

```typescript
async writeFile(
  filePath: string,
  content: string,
  options?: WriteOptions
): Promise<WriteResult>
```

**Parameters**:

* `filePath`: File path
* `content`: File content
* `options`: Write options (optional)

**Return Value**: `WriteResult` - Write result

##### ensureDirectory()

Ensures a directory exists, creating it if it doesn't.

```typescript
async ensureDirectory(dirPath: string): Promise<void>
```

**Parameters**:

* `dirPath`: Directory path

## Type Definitions

### FileContent

Represents file content.

```typescript
interface FileContent {
  path: string;
  content: string;
  mode?: string;
}
```

**Properties**:

* `path`: File path
* `content`: File content
* `mode`: File mode (optional, default: `0o644`)

### WriteResult

Represents file write result.

```typescript
interface WriteResult {
  path: string;
  success: boolean;
  action: 'created' | 'updated' | 'skipped';
  error?: string;
  size?: number;
}
```

**Properties**:

* `path`: File path
* `success`: Write success flag
* `action`: Executed action
  * `created`: Newly created
  * `updated`: Overwritten
  * `skipped`: Skipped (dry-run or user declined)
* `error`: Error message (on write failure)
* `size`: Written file size (bytes)

### WriterOptions

Represents writer options.

```typescript
interface WriterOptions {
  force?: boolean;      // Skip overwrite confirmation (default: false)
  dryRun?: boolean;     // Dry-run mode (default: false)
  verbose?: boolean;    // Verbose logging (default: false)
}
```

### WriteOptions

Represents write options (for individual files).

```typescript
interface WriteOptions {
  overwrite?: boolean;  // Overwrite existing file
  skipPrompt?: boolean; // Skip overwrite confirmation prompt
}
```

## Prompt Service

### PromptService

Service providing interactive prompts.

```typescript
class PromptService {
  async confirmOverwrite(filePath: string): Promise<boolean>
  async confirmOverwriteAll(): Promise<OverwriteAction>
}
```

#### confirmOverwrite()

Confirms overwrite for a single file.

**Parameters**:

* `filePath`: File path

**Return Value**: `boolean` - `true`: Overwrite, `false`: Skip

**Example**:

```typescript
const prompt = new PromptService();
const shouldOverwrite = await prompt.confirmOverwrite('.kiro/specs/api-spec/requirements.md');
```

#### confirmOverwriteAll()

Confirms overwrite action for all files.

**Return Value**: `OverwriteAction`

```typescript
type OverwriteAction = 'yes' | 'no' | 'all' | 'none';
```

* `yes`: Overwrite this file only
* `no`: Skip this file
* `all`: Overwrite all
* `none`: Skip all

## Path Utilities

### PathUtils

Provides path conversion utilities.

```typescript
class PathUtils {
  static normalize(path: string): string
  static join(...paths: string[]): string
  static isAbsolute(path: string): boolean
  static relative(from: string, to: string): string
}
```

#### normalize()

Normalizes a path.

```typescript
const normalized = PathUtils.normalize('.kiro/specs//api-spec/requirements.md');
// => '.kiro/specs/api-spec/requirements.md'
```

#### join()

Joins multiple paths.

```typescript
const joined = PathUtils.join('.kiro', 'specs', 'api-spec', 'requirements.md');
// => '.kiro/specs/api-spec/requirements.md'
```

## Error Handling

### FileSystemError

Custom error class representing filesystem errors.

```typescript
class FileSystemError extends Error {
  constructor(
    public code: string,
    message: string,
    public path?: string
  ) {
    super(message);
  }
}
```

**Error Codes**:

* `EACCES`: Permission error
* `ENOENT`: File or directory not found
* `EEXIST`: File already exists
* `ENOSPC`: Disk space insufficient

## Usage Examples

### Basic Usage

```typescript
import { FileWriter } from './filesystem/writer';

// Initialize FileWriter
const writer = new FileWriter({
  force: false,
  dryRun: false,
  verbose: true
});

// Write files
const results = await writer.writeFiles([
  { path: '.kiro/specs/api-spec/requirements.md', content: '# Requirements' },
  { path: '.kiro/steering/tech.md', content: '# Tech Stack' }
]);

results.forEach(result => {
  if (result.success) {
    console.log(`✓ ${result.action}: ${result.path} (${result.size} bytes)`);
  } else {
    console.error(`✗ ${result.path}: ${result.error}`);
  }
});
```

### Dry-Run Mode

```typescript
const writer = new FileWriter({
  force: false,
  dryRun: true,  // Dry-run mode
  verbose: true
});

const results = await writer.writeFiles([
  { path: '.kiro/specs/api-spec/requirements.md', content: '...' }
]);

// Sample output: [DRY RUN] Would create: .kiro/specs/api-spec/requirements.md
```

### Force Overwrite

```typescript
const writer = new FileWriter({
  force: true,   // Skip overwrite confirmation
  dryRun: false,
  verbose: false
});

const results = await writer.writeFiles([
  { path: '.kiro/specs/api-spec/requirements.md', content: '...' }
]);
```

### Overwrite Confirmation Prompt

```typescript
import { PromptService } from './filesystem/prompt';

const prompt = new PromptService();

// Single file confirmation
const shouldOverwrite = await prompt.confirmOverwrite('.kiro/specs/api-spec/requirements.md');

if (shouldOverwrite) {
  await writer.writeFile('.kiro/specs/api-spec/requirements.md', content);
}

// All files confirmation
const action = await prompt.confirmOverwriteAll();

switch (action) {
  case 'all':
    // Overwrite all
    break;
  case 'none':
    // Skip all
    break;
  case 'yes':
    // Overwrite this file only
    break;
  case 'no':
    // Skip this file
    break;
}
```

### Automatic Directory Creation

```typescript
const writer = new FileWriter({ force: false, dryRun: false });

// Automatically create directory if it doesn't exist
await writer.ensureDirectory('.kiro/specs/new-project');

// Write file (directory is automatically created)
await writer.writeFile('.kiro/specs/new-project/requirements.md', '# Requirements');
```

## Performance

### Write Speed

* **Single file**: Less than 1ms (SSD environment)
* **Large files**: Within 1 second for 100 files
* **Directory creation**: Within 10ms for recursive directory creation

## Related Pages

* [GitHub Fetcher API](/api/github-fetcher): Details on GitHub integration
* [API Specification](/api/): API specification overview

---

---
url: /kirox/guide/getting-started.md
description: Installation and initial setup for Kirox CLI
---

# Getting Started

This guide explains how to get started with Kirox CLI.

## Prerequisites

To use Kirox CLI, you need the following environment:

* **Node.js 18.0.0 or higher**: Download from [Node.js official website](https://nodejs.org/)
* **npm 9 or higher**: Included with Node.js
* **Git**: Version control tool (optional)

Verify versions:

```bash
node --version  # v18.0.0 or higher
npm --version   # 9.0.0 or higher
```

## Installation

Kirox CLI **does not require global installation** and can be run immediately with the npx command.

### Run with npx (Recommended)

```bash
npx kirox owner/repo -p project-name
```

This method is recommended as it always runs the latest version.

### Global Installation

If you use it frequently, you can install it globally:

```bash
npm install -g kirox
kirox owner/repo -p project-name
```

## First Run

### Basic Usage

Fetch specifications from a GitHub repository:

```bash
npx kirox yukihirop/my-project -p my-spec
```

### Interactive Mode

Running without options allows you to configure interactively:

```bash
npx kirox
```

Follow the prompts to enter:

1. GitHub repository (e.g., `yukihirop/my-project`)
2. Branch (optional)
3. Subdirectory (optional)
4. Project name (multiple selection available)

## GitHub Authentication (Optional)

To access private repositories or to relax GitHub API rate limits, set up a Personal Access Token (PAT).

### Obtaining a PAT

1. Go to [GitHub Settings → Developer settings → Personal access tokens](https://github.com/settings/tokens)
2. Click "Generate new token (classic)"
3. Select the following scopes:
   * `public_repo`: Read public repositories
   * `repo`: Read private repositories (if needed)
4. Generate and copy the token

### Setting Environment Variables

```bash
# macOS / Linux
export GITHUB_TOKEN=ghp_your_token_here

# Windows (PowerShell)
$env:GITHUB_TOKEN="ghp_your_token_here"
```

To set permanently, add to `.bashrc`, `.zshrc`, or `.profile`:

```bash
echo 'export GITHUB_TOKEN=ghp_your_token_here' >> ~/.bashrc
source ~/.bashrc
```

## Verification

Verify that Kirox CLI is working correctly with the following command:

```bash
npx kirox --help
```

If the help message is displayed, the installation was successful.

## Next Steps

* [Basic Usage](/guide/basic-usage): Details on commands and options
* [Advanced Usage](/guide/advanced-usage): Configuration files and advanced features
* [CLI Reference](/cli/): Reference for all commands

---

---
url: /kirox/api/github-fetcher.md
description: GitHub integration module API specification
---

# GitHub Fetcher API

API specification for the module that fetches files from GitHub repositories.

## Overview

GitHub Fetcher (`src/github/`) is a layer that retrieves repository content using the GitHub REST API.

**Key Features**:

* Fetch repository content (directory listings, file content)
* Decode base64-encoded content
* Parallel file fetching and semaphore control
* Rate limit monitoring and handling

## Directory Structure

```
src/github/
├── fetcher.ts        # GitHubFetcher: Main file fetching logic
├── client.ts         # Octokit client initialization and authentication
├── semaphore.ts      # Semaphore for concurrency control utility
├── rate-limit.ts     # Rate limit checking and monitoring
└── types.ts          # GitHub layer type definitions (FetchResult, FileContent, etc.)
```

## Main Classes and Interfaces

### GitHubFetcher

Main class for fetching files from repositories.

#### Constructor

```typescript
class GitHubFetcher {
  constructor(
    private octokit: Octokit,
    private options: FetcherOptions
  ) {}
}
```

**Parameters**:

* `octokit`: Octokit instance
* `options`: Fetcher options

#### Methods

##### fetchFiles()

Fetches files from the specified repository.

```typescript
async fetchFiles(
  owner: string,
  repo: string,
  paths: string[],
  ref?: string
): Promise<FetchResult[]>
```

**Parameters**:

* `owner`: Repository owner name
* `repo`: Repository name
* `paths`: Array of file paths to fetch
* `ref`: Branch name, tag, or commit SHA (optional)

**Return Value**: `FetchResult[]` - Array of fetch results

**Example**:

```typescript
const fetcher = new GitHubFetcher(octokit, options);
const results = await fetcher.fetchFiles(
  'yukihirop',
  'my-project',
  ['.kiro/specs/api-spec/requirements.md', '.kiro/steering/tech.md'],
  'main'
);
```

##### fetchDirectoryContents()

Fetches the contents list of the specified directory.

```typescript
async fetchDirectoryContents(
  owner: string,
  repo: string,
  path: string,
  ref?: string
): Promise<DirectoryContent[]>
```

**Parameters**:

* `owner`: Repository owner name
* `repo`: Repository name
* `path`: Directory path
* `ref`: Branch name, tag, or commit SHA (optional)

**Return Value**: `DirectoryContent[]` - Array of directory contents

##### fetchFilesInParallel()

Fetches multiple files in parallel (max 5 concurrent).

```typescript
async fetchFilesInParallel(
  owner: string,
  repo: string,
  paths: string[],
  ref?: string
): Promise<FetchResult[]>
```

**Parameters**:

* `owner`: Repository owner name
* `repo`: Repository name
* `paths`: Array of file paths to fetch
* `ref`: Branch name, tag, or commit SHA (optional)

**Return Value**: `FetchResult[]` - Array of fetch results

## Type Definitions

### FetchResult

Represents file fetch result.

```typescript
interface FetchResult {
  path: string;
  content: string | null;
  success: boolean;
  error?: string;
  size?: number;
  sha?: string;
}
```

**Properties**:

* `path`: File path
* `content`: File content (on successful fetch)
* `success`: Fetch success flag
* `error`: Error message (on failed fetch)
* `size`: File size (bytes)
* `sha`: Git object SHA

### DirectoryContent

Represents directory content.

```typescript
interface DirectoryContent {
  name: string;
  path: string;
  type: 'file' | 'dir';
  size?: number;
  sha: string;
}
```

**Properties**:

* `name`: File/directory name
* `path`: Relative path
* `type`: Type (`file` or `dir`)
* `size`: File size (bytes, files only)
* `sha`: Git object SHA

### FetcherOptions

Represents fetcher options.

```typescript
interface FetcherOptions {
  maxConcurrency?: number;  // Max concurrency (default: 5)
  timeout?: number;          // Timeout in milliseconds (default: 30000)
  retries?: number;          // Number of retries (default: 3)
}
```

## Semaphore Control

### Semaphore

Semaphore class for controlling concurrency.

```typescript
class Semaphore {
  constructor(private maxConcurrency: number) {}

  async acquire(): Promise<void>
  release(): void
}
```

**Usage Example**:

```typescript
const semaphore = new Semaphore(5);

await semaphore.acquire();
try {
  // Concurrent processing
  await fetchFile();
} finally {
  semaphore.release();
}
```

## Rate Limit Management

### RateLimitManager

Manages GitHub API rate limits.

```typescript
class RateLimitManager {
  async checkRateLimit(octokit: Octokit): Promise<RateLimitStatus>
  async waitForRateLimit(octokit: Octokit): Promise<void>
}
```

#### checkRateLimit()

Gets current rate limit status.

**Return Value**: `RateLimitStatus`

```typescript
interface RateLimitStatus {
  limit: number;       // Rate limit (number of requests)
  remaining: number;   // Remaining requests
  reset: number;       // Reset time (UNIX timestamp)
  used: number;        // Used requests
}
```

## Error Handling

### GitHubAPIError

Custom error class representing GitHub API errors.

```typescript
class GitHubAPIError extends Error {
  constructor(
    public statusCode: number,
    message: string,
    public response?: any
  ) {
    super(message);
  }
}
```

**Error Codes**:

* `404`: Repository or file not found
* `403`: Rate limit exceeded or insufficient permissions
* `401`: Authentication error
* `500`: Server error

## Usage Examples

### Basic Usage

```typescript
import { Octokit } from 'octokit';
import { GitHubFetcher } from './github/fetcher';

// Initialize Octokit client
const octokit = new Octokit({
  auth: process.env.GITHUB_TOKEN
});

// Initialize GitHubFetcher
const fetcher = new GitHubFetcher(octokit, {
  maxConcurrency: 5,
  timeout: 30000,
  retries: 3
});

// Fetch files
const results = await fetcher.fetchFiles(
  'yukihirop',
  'my-project',
  ['.kiro/specs/api-spec/requirements.md'],
  'main'
);

results.forEach(result => {
  if (result.success) {
    console.log(`✓ ${result.path}: ${result.size} bytes`);
  } else {
    console.error(`✗ ${result.path}: ${result.error}`);
  }
});
```

### Parallel File Fetching

```typescript
const paths = [
  '.kiro/specs/api-spec/requirements.md',
  '.kiro/specs/api-spec/design.md',
  '.kiro/specs/api-spec/tasks.md',
  '.kiro/steering/tech.md',
  '.kiro/steering/structure.md'
];

const results = await fetcher.fetchFilesInParallel(
  'yukihirop',
  'my-project',
  paths,
  'main'
);
```

### Fetch Directory Contents

```typescript
const contents = await fetcher.fetchDirectoryContents(
  'yukihirop',
  'my-project',
  '.kiro/specs',
  'main'
);

contents.forEach(item => {
  console.log(`${item.type}: ${item.path}`);
});
```

## Performance

### Parallel Processing

* **Max concurrency**: 5 requests
* **Large file fetching**: Within 30 seconds for 50 files
* **Time reduction**: Approximately 80% time reduction (with parallel processing)

### Rate Limits

* **Without authentication**: 60 requests/hour
* **With authentication**: 5,000 requests/hour

## Related Pages

* [FileSystem Writer API](/api/filesystem-writer): Details on filesystem operations
* [API Specification](/api/): API specification overview

---

---
url: /kirox/guide.md
description: User guide for Kirox CLI
---

# Guide

Kirox CLI is an npx command-line tool to fetch Kiro specification and steering files from remote GitHub repositories.

## Guide Index

### [Getting Started](/guide/getting-started)

Learn how to install and set up Kirox CLI.

### [Basic Usage](/guide/basic-usage)

Learn the basic commands and options of Kirox CLI.

### [Advanced Usage](/guide/advanced-usage)

Utilize advanced features such as configuration files, branch specification, and subdirectory support.

### [Troubleshooting](/guide/troubleshooting)

Explore common issues and their solutions.

## Key Features

* **Instant execution with npx**: No global installation required
* **Overwrite protection**: Confirmation prompt for existing files
* **Progress visualization**: Real-time display of file fetching progress
* **Flexible configuration**: Customize behavior with .kiroxrc.json
* **Error handling**: Clear error messages and solutions

## Next Steps

For beginners, we recommend starting with [Getting Started](/guide/getting-started).

---

---
url: /kirox/PERFORMANCE_ANALYSIS.md
---
# Kirox CLI - Performance Analysis Report

## Executive Summary

**Date**: 2025-10-06
**Version**: 0.1.0
**Status**: ✅ All performance targets exceeded

## Performance Targets vs Actuals

| Metric | Target | Actual | Status |
|--------|--------|--------|--------|
| 50 files fetch time | < 30 seconds | 27ms | ✅ **99.9% faster** |
| Memory usage (50 files × 500KB) | < 100MB | 25.88MB | ✅ **74% under budget** |
| Max concurrent requests | 5 | 5 | ✅ **As designed** |
| 30 files parallel fetch | N/A | 63ms | ✅ **Excellent** |
| Throughput | > 10 files/sec | 925.93 files/sec | ✅ **92x target** |

## Analysis

### Bottleneck Identification

**Conducted**: Code review and performance test analysis
**Result**: No significant bottlenecks found

1. **API Calls**: Optimized with semaphore-controlled parallel fetching (max 5 concurrent)
2. **Memory Usage**: Well within limits, no memory leaks detected
3. **File Operations**: Efficient with automatic directory creation
4. **Error Handling**: Does not impact performance

### Optimizations Implemented

#### 1. Eliminated Redundant Filter Operations

**Before**:

```typescript
const allFiles: ContentItem[] = [
  ...specContents.filter((item) => item.type === 'file'),
  ...steeringContents.filter((item) => item.type === 'file'),
];

if (args.verbose) {
  logger.info('Directory listings fetched', {
    specFiles: specContents.filter((item) => item.type === 'file').length, // Redundant
    steeringFiles: steeringContents.filter((item) => item.type === 'file').length, // Redundant
    total: allFiles.length,
  });
}
```

**After**:

```typescript
const specFiles = specContents.filter((item) => item.type === 'file');
const steeringFiles = steeringContents.filter((item) => item.type === 'file');
const allFiles: ContentItem[] = [...specFiles, ...steeringFiles];

if (args.verbose) {
  logger.info('Directory listings fetched', {
    specFiles: specFiles.length,
    steeringFiles: steeringFiles.length,
    total: allFiles.length,
  });
}
```

**Impact**: Eliminated 2 redundant array iterations in verbose mode

#### 2. Verified Semaphore Concurrency Control

**Implementation**: `Semaphore` class with max 5 concurrent operations
**Verification**: Performance tests confirm max concurrent requests = 5
**Impact**: Prevents GitHub API rate limiting while maximizing throughput

#### 3. Parallel Fetching with Promise.allSettled

**Implementation**: All file fetches execute in parallel with partial failure tolerance
**Verification**: 30 files fetched in 63ms (parallel) vs ~300ms (sequential)
**Impact**: ~80% time reduction for multiple file operations

### Memory Leak Verification

**Method**: Memory delta tracking before/after 50-file operation
**Result**: 25.88MB delta for 25MB content (500KB × 50 files)
**Conclusion**: ✅ No memory leaks detected, overhead within acceptable range (3.5%)

### Unnecessary API Calls Analysis

**Review**: Examined all GitHub API interactions
**Findings**:

* ✅ Directory listings: 2 calls (spec + steering) - necessary
* ✅ File contents: 1 call per file - necessary
* ✅ Rate limit check: Built into retry logic - efficient

**Conclusion**: No unnecessary API calls found

## Architecture Assessment

### Strengths

1. **Semaphore Pattern**: Elegant concurrency control without resource contention
2. **Parallel Execution**: Optimal use of Promise.allSettled for bulk operations
3. **Error Isolation**: Partial failures don't block successful operations
4. **Memory Efficiency**: No accumulation or leaks

### Current Limitations

1. **Max File Count**: Hard limit of 100 files (by design, prevents API abuse)
2. **Max File Size**: 1MB per file (GitHub API limitation)
3. **Concurrency**: Fixed at 5 (could be configurable, but current value is optimal)

## Recommendations

### Priority: LOW (Current performance exceeds all targets)

1. ✅ **Filter Optimization**: Implemented (eliminated redundant operations)
2. ⏭️ **Configurable Concurrency**: Not needed (5 is optimal for GitHub API)
3. ⏭️ **Caching**: Not needed (CLI is run-once tool, caching adds complexity)
4. ⏭️ **Rate Limit Pre-check**: Already implemented in retry logic

## Test Coverage

* **Total Tests**: 286
  * Unit: 249
  * Integration: 18
  * E2E: 13
  * Performance: 6
* **Pass Rate**: 100%
* **Test Duration**: 1.32s

## Conclusion

**Status**: ✅ **PRODUCTION READY**

All performance targets have been exceeded by significant margins:

* Speed: 99.9% faster than target
* Memory: 74% under budget
* Throughput: 92x target performance

**Recommendation**: No further optimization required. Current implementation is highly efficient and ready for production use.

## Changelog

### 2025-10-06

* Eliminated redundant filter operations in verbose logging
* Verified no memory leaks (25.88MB for 25MB content)
* Confirmed no unnecessary API calls
* All performance tests passing with excellent metrics

---

---
url: /kirox/cli/kirox.md
description: Kirox CLI main command
---

# kirox Command

Fetches files from `.kiro/specs/` and `.kiro/steering/` in GitHub repositories.

## Syntax

```bash
npx kirox [<owner/repo>[#branch]] [options]
```

## Arguments

### `<owner/repo>[#branch]`

Specify a GitHub repository (optional).

**Format**:

* `owner/repo`: Specify repository only (uses default branch)
* `owner/repo#branch`: Specify branch as well

**Examples**:

```bash
npx kirox yukihirop/my-project
npx kirox yukihirop/my-project#develop
npx kirox yukihirop/my-project#feature/new-feature
```

**When omitted**: Interactive mode prompts for input

## Options

### `-p, --project <projects>`

Specify project name(s) to fetch (comma-separated for multiple).

**Type**: `string`

**Examples**:

```bash
# Single project
npx kirox yukihirop/my-project -p api-spec

# Multiple projects
npx kirox yukihirop/my-project -p api-spec,web-spec,mobile-spec
```

**When omitted**:

* Non-interactive mode: Error (except when using `--steering` option)
* Interactive mode: Auto-detect and suggest available projects

### `--track`

Track changes in remote repository.

**Type**: `boolean`
**Default**: `false`

**Behavior**:

* First run: Fetch all files and save metadata
* Subsequent runs: Fetch only changed files

**Example**:

```bash
npx kirox yukihirop/my-project -p api-spec --track
```

### `--steering`

Fetch only `.kiro/steering/` and skip project specifications.

**Type**: `boolean`
**Default**: `false`

**Example**:

```bash
npx kirox yukihirop/my-project --steering
```

::: tip Tip
Useful when you only want to fetch steering information shared across the team.
:::

### `-f, --force`

Overwrite existing files without confirmation.

**Type**: `boolean`
**Default**: `false`

**Example**:

```bash
npx kirox yukihirop/my-project -p api-spec --force
```

::: warning Warning
The `--force` option overwrites existing files without warning. Use with caution.
:::

### `--dry-run`

Simulate file writing and display which files would be fetched.

**Type**: `boolean`
**Default**: `false`

**Example**:

```bash
npx kirox yukihirop/my-project -p api-spec --dry-run
```

**Sample Output**:

```
[DRY RUN] The following files would be fetched:
  .kiro/specs/api-spec/requirements.md
  .kiro/specs/api-spec/design.md
  .kiro/specs/api-spec/tasks.md
  .kiro/specs/api-spec/spec.json
  .kiro/steering/tech.md
```

### `--verbose`

Display detailed logs.

**Type**: `boolean`
**Default**: `false`

**Example**:

```bash
npx kirox yukihirop/my-project -p api-spec --verbose
```

**Sample Output**:

```
[DEBUG] Loading config from .kiroxrc.json
[DEBUG] Fetching repository: yukihirop/my-project
[DEBUG] Branch: main
[DEBUG] Project: api-spec
[INFO] Fetching .kiro/specs/api-spec/requirements.md...
[INFO] Fetched 1024 bytes
```

### `--subdirectory <path>`

Fetch `.kiro/` files from a subdirectory within the repository.

**Type**: `string`

**Examples**:

```bash
# Fetch from backend directory in monorepo
npx kirox yukihirop/monorepo -p api-spec --subdirectory backend

# Nested subdirectory
npx kirox yukihirop/monorepo -p api-spec --subdirectory packages/core
```

### `-c, --config <path>`

Specify configuration file path.

**Type**: `string`
**Default**: `.kiroxrc.json`

**Example**:

```bash
npx kirox yukihirop/my-project -p api-spec --config custom-config.json
```

### `-h, --help`

Display help message.

**Example**:

```bash
npx kirox --help
```

### `-V, --version`

Display Kirox CLI version.

**Example**:

```bash
npx kirox --version
```

## Interactive Mode

Run without arguments and options to configure interactively.

```bash
npx kirox
```

**Prompts**:

1. **Repository input**: Enter in `owner/repo` format
2. **Branch selection**: Select from available branches with searchable checkbox (optional)
3. **Subdirectory selection**: Select from detected subdirectories (optional)
4. **Project selection**: Select from available projects with searchable checkbox (multiple selection available)

## Usage Examples

### Basic Usage

```bash
# Fetch specific project
npx kirox yukihirop/my-project -p api-spec
```

### Specify Branch

```bash
# Fetch from develop branch
npx kirox yukihirop/my-project#develop -p api-spec

# Fetch from feature/new-feature branch
npx kirox yukihirop/my-project#feature/new-feature -p api-spec
```

### Multiple Projects

```bash
# Fetch multiple projects
npx kirox yukihirop/my-project -p api-spec,web-spec,mobile-spec
```

### Subdirectory

```bash
# Fetch from backend directory in monorepo
npx kirox yukihirop/monorepo -p api-spec --subdirectory backend
```

### Option Combinations

```bash
# Dry run + verbose logs
npx kirox yukihirop/my-project -p api-spec --dry-run --verbose

# Force overwrite + update tracking
npx kirox yukihirop/my-project -p api-spec --force --track

# Steering only + custom config file
npx kirox yukihirop/my-project --steering --config team-config.json
```

## Execution Flow

1. **Load configuration**: `.kiroxrc.json` or custom config file
2. **GitHub API authentication**: `GITHUB_TOKEN` environment variable (optional)
3. **Fetch repository information**: Branch, subdirectory, project list
4. **Fetch files**: Fetch files in parallel (max 5 concurrent)
5. **Write files**: Save to local `.kiro/` directory
6. **Display summary**: Show success/failure file counts

## Environment Variables

### GITHUB\_TOKEN

Used for GitHub API authentication.

```bash
export GITHUB_TOKEN=ghp_your_token_here
```

Required for accessing private repositories or relaxing rate limits.

## Exit Codes

| Code | Description |
|-------|------|
| `0` | Success |
| `1` | Argument error |
| `2` | GitHub API error |
| `3` | Filesystem error |
| `4` | Configuration error |

## Related Pages

* [Basic Usage](/guide/basic-usage): Basic command usage
* [Advanced Usage](/guide/advanced-usage): Configuration files, branch specification, subdirectory support
* [Troubleshooting](/guide/troubleshooting): Common issues and solutions

---

---
url: /kirox/llms.md
description: llms.txt files for LLMs
---

# LLMs.txt

This page provides documentation files for LLMs to reference.

## Overview

Kirox documentation is provided in a format that is easy for LLMs to understand.

## Available Files

### llms.txt

A summary version containing a brief overview of the project and links to major documentation.

* [llms.txt](/llms.txt)

This file contains the following content:

* Project overview
* Links to major documentation
* Guides (Getting Started, Basic Usage, Advanced Usage, Troubleshooting)
* CLI Reference (kirox, add, completion)
* API Specifications (GitHub Fetcher, FileSystem Writer)
* Configuration (.kiroxrc.json)

### llms-full.txt

A complete version containing the full documentation of the project.

* [llms-full.txt](/llms-full.txt)

This file contains the following content:

* Complete content of all guide documents
* Complete CLI reference
* Complete API specifications
* Complete configuration reference
* Complete performance analysis report

## Usage

### Recommendations for LLMs

1. **When you need a quick reference**: Use `llms.txt`
2. **When you need detailed information**: Use `llms-full.txt`
3. **When searching for a specific topic**: Use keyword search within the above files

## Technical Details

These files are automatically generated by the `vitepress-plugin-llms` plugin.

Generated files are created during the VitePress build process and placed at the site root.

## File Structure

```
.kirox/
├── specs/
│   └── <project-name>/
│       ├── requirements.md
│       ├── design.md
│       └── tasks.md
└── steering/
    ├── tech.md
    ├── product.md
    └── structure.md
```

## Download

You can directly download or view the generated files:

* [llms.txt](/llms.txt) - Summary version (lightweight)
* [llms-full.txt](/llms-full.txt) - Complete version (detailed)

::: tip Tip
Use `llms.txt` when using Kirox CLI for the first time, and use `llms-full.txt` when you need detailed technical information.
:::

## Related Resources

* [Guide](/guide/) - Usage guide
* [CLI Reference](/cli/) - CLI command reference
* [API Documentation](/api/) - API specifications
* [Configuration](/config/) - Configuration reference

---

---
url: /kirox/llms/llms.md
description: Details about llms.txt files
---

# LLMs.txt File Details

This page provides detailed information about the documentation files (`llms.txt` and `llms-full.txt`) for LLMs to reference.

## About llms.txt

### Purpose

`llms.txt` is a summary version document for LLMs to understand Kirox CLI. It includes a project overview and links to major documentation.

### Content

1. **Project Overview**
   * What is Kirox
   * Key features
   * Usage overview

2. **Links to Major Documentation**
   * Guides
   * CLI Reference
   * API Specifications
   * Configuration

### Usage Example

When an LLM is asked about Kirox CLI, it can quickly understand the overview by first referencing `llms.txt`.

## About llms-full.txt

### Purpose

`llms-full.txt` is a complete document for LLMs to understand detailed technical information about Kirox CLI.

### Content

1. **All Guide Documents**
   * Getting Started
   * Basic Usage
   * Advanced Usage
   * Troubleshooting

2. **Complete CLI Reference**
   * kirox command
   * add subcommand
   * completion subcommand

3. **API Specifications**
   * GitHub Fetcher
   * FileSystem Writer

4. **Configuration Reference**
   * .kiroxrc.json
   * Configuration options
   * Configuration examples

5. **Performance Analysis**
   * Performance metrics
   * Benchmark results
   * Optimization methods

### Usage Example

When an LLM needs to provide accurate answers to specific technical questions, it references `llms-full.txt`.

## Generation Process

These files are automatically generated by the `vitepress-plugin-llms` plugin.

### Generation Timing

1. Generated during VitePress build process
2. Generated when development server starts
3. Distributed as build artifacts

### Generation Location

Generated files are placed in the following location:

```
docs/.vitepress/dist/
├── llms.txt
└── llms-full.txt
```

## Browser Access

You can access these files in the built site at the following URLs:

* [llms.txt](https://yukihirop.github.io/kirox/llms.txt)
* [llms-full.txt](https://yukihirop.github.io/kirox/llms-full.txt)

## Download

Generated files are accessible at the following URLs:

* [llms.txt](https://yukihirop.github.io/kirox/llms.txt) - Summary version
* [llms-full.txt](https://yukihirop.github.io/kirox/llms-full.txt) - Complete version

## LLM Integration

### LangChain Example

```python
from langchain.document_loaders import TextLoader

# Load llms.txt
loader = TextLoader('https://yukihirop.github.io/kirox/llms.txt')
docs = loader.load()

# Create vector store
vectorstore = FAISS.from_documents(docs, embeddings)

# Answer questions
response = chain.run("How do I use Kirox CLI?")
```

### OpenAI API Example

```python
import requests

# Fetch llms.txt
response = requests.get('https://yukihirop.github.io/kirox/llms.txt')
llms_content = response.text

# Send to OpenAI API
response = openai.ChatCompletion.create(
    model="gpt-4",
    messages=[
        {"role": "system", "content": llms_content},
        {"role": "user", "content": "How do I use Kirox CLI?"}
    ]
)
```

## File Format

### llms.txt Format

```
# Kirox

> Recycle .kiro CLI

CLI tool to fetch Kiro specification and steering files from remote GitHub repositories

## Table of Contents

### Guide

- [Guide](/kirox/guide.md): User guide for Kirox CLI
- [Getting Started](/kirox/guide/getting-started.md): ...
...
```

### llms-full.txt Format

```
---
url: /kirox/config/kiroxrc.md
description: Kirox CLI configuration file reference
---

# .kiroxrc.json

Reference for the Kirox CLI configuration file.
...
```

## Best Practices

### Writing Optimized for LLMs

1. **Clear headings**: Use clear titles for each section
2. **Concrete examples**: Include code examples and usage scenarios
3. **Concise descriptions**: Avoid long sentences, use bullet points
4. **Structured information**: Use tables and lists to organize information

### File Size Management

* `llms.txt`: Approximately 40 lines (summary version)
* `llms-full.txt`: Approximately 3,000+ lines (complete version)

## Troubleshooting

### File Not Found

1. Check if the build completed successfully
2. Check the `.vitepress/dist/` directory
3. Verify plugin configuration is correct

### Outdated Content

1. Update the source documentation files
2. Rebuild VitePress
3. Clear cache

## Related Resources

* [llms.txt](/llms.txt) - Summary version documentation
* [llms-full.txt](/llms-full.txt) - Complete version documentation
* [vitepress-plugin-llms](https://github.com/llm-txt/vitepress-plugin-llms) - Plugin GitHub
* [LLM.text Standard](https://llmtext.com/) - llms.txt file specification

---

---
url: /kirox/guide/troubleshooting.md
description: Common issues and solutions
---

# Troubleshooting

This guide explains potential issues when using Kirox CLI and their solutions.

## Installation and Execution

### Node.js Version Error

**Error Message**:

```
Error: Kirox requires Node.js 18.0.0 or higher
```

**Cause**: Node.js version is outdated

**Solution**:

```bash
# Check Node.js version
node --version

# Upgrade to Node.js 18 or higher
# Download the latest version from https://nodejs.org/

# Using nvm
nvm install 18
nvm use 18
```

### npx Command Not Found

**Error Message**:

```
command not found: npx
```

**Cause**: npm is outdated or not installed

**Solution**:

```bash
# Check npm version
npm --version

# Upgrade npm
npm install -g npm@latest
```

## GitHub API Related

### Rate Limit Error

**Error Message**:

```
Error: GitHub API rate limit exceeded
```

**Cause**: Reached GitHub API rate limit (without authentication: 60 requests/hour)

**Solution**:

1. Set GitHub Personal Access Token (PAT):

```bash
export GITHUB_TOKEN=ghp_your_token_here
```

2. After configuration, rate limit is relaxed to 5,000 requests/hour

3. Check current rate limit status:

```bash
npx kirox owner/repo -p project --verbose
```

### Authentication Error

**Error Message**:

```
Error: Bad credentials
```

**Cause**: Invalid GitHub Personal Access Token

**Solution**:

1. Verify PAT is correct:

```bash
echo $GITHUB_TOKEN
```

2. Verify PAT scope (requires `public_repo` or `repo`)

3. Generate a new PAT:
   * [GitHub Settings → Developer settings → Personal access tokens](https://github.com/settings/tokens)

### Repository Not Found

**Error Message**:

```
Error: Repository not found: owner/repo
```

**Cause**: Repository does not exist or no access permission

**Solution**:

1. Verify repository name spelling
2. For private repositories, set `GITHUB_TOKEN`
3. Verify access permissions to the repository

## File Fetching Related

### File Not Found

**Error Message**:

```
Warning: .kiro/specs/project-name/ not found in repository
```

**Cause**: Specified project does not exist in the repository

**Solution**:

1. Verify project name spelling
2. Check branch (may exist in a different branch):

```bash
npx kirox owner/repo#develop -p project-name
```

3. Check subdirectory (for monorepos):

```bash
npx kirox owner/repo -p project-name --subdirectory path/to/subdir
```

4. Check available projects in the repository:

```bash
# Auto-detect in interactive mode
npx kirox
```

### File Size Limit Error

**Error Message**:

```
Error: File too large (max 1MB via GitHub API)
```

**Cause**: GitHub's Content API cannot fetch files larger than 1MB

**Solution**:

1. Check file size and split if necessary
2. Do not include large binary files in the `.kiro/` directory
3. When using Git LFS, fetching via API may be difficult

## Local Filesystem Related

### Write Permission Error

**Error Message**:

```
Error: EACCES: permission denied
```

**Cause**: No write permission to the directory

**Solution**:

1. Check directory permissions:

```bash
ls -la .kiro/
```

2. Correct permissions:

```bash
chmod -R u+w .kiro/
```

3. Running with sudo is not recommended (security risk)

### Existing File Overwrite Confirmation

**Behavior**: Asked to confirm overwriting existing files

**Solutions**:

1. Select in confirmation prompt:
   * `y`: Overwrite
   * `n`: Skip
   * `a`: Overwrite all

2. Skip confirmation (`--force` option):

```bash
npx kirox owner/repo -p project --force
```

::: warning Warning
The `--force` option overwrites existing files without warning.
:::

3. Preview beforehand with dry run:

```bash
npx kirox owner/repo -p project --dry-run
```

## Network Related

### Timeout Error

**Error Message**:

```
Error: Request timeout
```

**Cause**: Network connection is slow or unstable

**Solution**:

1. Check internet connection
2. Check firewall or proxy settings
3. Retry:

```bash
npx kirox owner/repo -p project
```

### Proxy Configuration

When accessing GitHub API through a proxy:

```bash
# HTTP proxy
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# Authenticated proxy
export HTTP_PROXY=http://user:pass@proxy.example.com:8080
```

## Other Issues

### Unexpected Errors

**Solutions**:

1. Enable verbose logging:

```bash
npx kirox owner/repo -p project --verbose
```

2. Check debug logs:

```bash
DEBUG=kirox:* npx kirox owner/repo -p project
```

3. Use the latest version (npx automatically uses the latest)

4. If the issue persists, report an issue on the [GitHub repository](https://github.com/yukihirop/kirox/issues)

### Displaying Help

To get hints for problem-solving:

```bash
# General help
npx kirox --help

# Subcommand help
npx kirox add --help
npx kirox completion --help
```

## Further Support

* [GitHub Issues](https://github.com/yukihirop/kirox/issues): Bug reports and feature requests
* [GitHub Discussions](https://github.com/yukihirop/kirox/discussions): Questions and discussions
* [CLI Reference](/cli/): Details on commands and options