Skip to content

Commit b6780b0

Browse files
committed
fix: Add TypeScript type annotations to fix validation errors
- Add type annotations to request/reply parameters in route handlers - Fix type issues in auth middleware for header values - Create type declaration file for @musistudio/llms module - Successfully rebuild project with no TypeScript errors - Setup project-specific CCR configuration from oppie-thunder
1 parent 9cd5587 commit b6780b0

15 files changed

+3661
-13
lines changed
77 KB
Binary file not shown.
Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Code Style and Conventions
2+
3+
## TypeScript Conventions
4+
- **File Structure**: Each module in its own file under `src/`
5+
- **Naming**:
6+
- camelCase for variables and functions
7+
- PascalCase for interfaces and types
8+
- UPPER_SNAKE_CASE for constants
9+
- **Type Safety**: Strict TypeScript with explicit type annotations
10+
- **Async/Await**: Preferred over callbacks for asynchronous operations
11+
12+
## Import Style
13+
- Use ES6 imports
14+
- Group imports: external deps, then internal modules
15+
- Example: `import { readFile } from 'fs/promises'`
16+
17+
## Error Handling
18+
- Try-catch blocks for async operations
19+
- Meaningful error messages with context
20+
- Log errors to file when LOG=true in config
21+
22+
## Configuration
23+
- JSON5 format (allows comments and trailing commas)
24+
- Environment variable expansion using `$HOME`
25+
- Validation on startup
26+
27+
## CLI Design
28+
- Clear command structure: `ccr <command> [options]`
29+
- Help text for all commands
30+
- Exit codes: 0 for success, 1 for errors
31+
32+
## API Design
33+
- RESTful endpoints
34+
- Request/response transformation via middleware
35+
- Streaming support for chat completions
Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Claude Code Router Project Overview
2+
3+
## Purpose
4+
Claude Code Router is a powerful tool to route Claude Code requests to different AI models from various providers. It acts as a middleware layer that intercepts Claude Code requests and forwards them to configured AI models based on custom routing rules.
5+
6+
## Key Features
7+
- **Model Routing**: Route requests to different models based on context (background tasks, reasoning, long context)
8+
- **Multi-Provider Support**: OpenRouter, DeepSeek, Ollama, Gemini, Volcengine, SiliconFlow, and more
9+
- **Request/Response Transformation**: Custom transformers to ensure API compatibility across providers
10+
- **Dynamic Model Switching**: Use `/model` command within Claude Code
11+
- **GitHub Actions Integration**: Run Claude Code in CI/CD pipelines
12+
- **Plugin System**: Extend functionality with custom transformers
13+
14+
## Tech Stack
15+
- **Language**: TypeScript
16+
- **Runtime**: Node.js
17+
- **Build Tool**: esbuild
18+
- **CLI Framework**: Custom implementation
19+
- **Server Framework**: Fastify (via @musistudio/llms dependency)
20+
- **Dependencies**:
21+
- @musistudio/llms (core LLM interaction logic)
22+
- tiktoken (token counting)
23+
- dotenv (environment variables)
24+
- json5 (JSON parsing with comments)
25+
26+
## Architecture
27+
- **Entry Point**: `src/cli.ts` - CLI command handler
28+
- **Server**: `src/server.ts` - HTTP server for routing requests
29+
- **Router**: `src/utils/router.ts` - Core routing logic
30+
- **Configuration**: JSON-based config at `~/.claude-code-router/config.json`
31+
- **Process Management**: PID files and reference counting for service lifecycle
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Claude Code Router Project Structure
2+
3+
## Directory Layout
4+
```
5+
claude-code-router/
6+
├── src/ # TypeScript source code
7+
│ ├── cli.ts # CLI entry point and command handler
8+
│ ├── index.ts # Main application initialization
9+
│ ├── server.ts # HTTP server setup
10+
│ ├── constants.ts # Global constants and paths
11+
│ ├── middleware/ # Request/response middleware
12+
│ │ └── auth.ts # API key authentication
13+
│ └── utils/ # Utility functions
14+
│ ├── router.ts # Core routing logic
15+
│ ├── codeCommand.ts # Code command execution
16+
│ ├── processCheck.ts # Process management
17+
│ ├── status.ts # Status checking
18+
│ ├── close.ts # Service shutdown
19+
│ ├── log.ts # Logging utilities
20+
│ └── index.ts # Config management utils
21+
├── blog/ # Documentation and guides
22+
├── ui/ # Web UI (beta)
23+
├── scripts/ # Build scripts
24+
├── dist/ # Compiled JavaScript (generated)
25+
├── config.example.json # Example configuration
26+
├── package.json # Project dependencies
27+
├── tsconfig.json # TypeScript configuration
28+
├── CLAUDE.md # Claude Code guidance
29+
└── README.md # Project documentation
30+
```
31+
32+
## Key Files
33+
- **Config**: `~/.claude-code-router/config.json` (runtime)
34+
- **PID File**: `~/.claude-code-router/.pid` (process tracking)
35+
- **Log File**: `~/.claude-code-router.log` (if enabled)
36+
- **Plugins**: `~/.claude-code-router/plugins/` (custom transformers)
Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Suggested Commands for Claude Code Router
2+
3+
## Build and Development
4+
- `npm install` - Install dependencies
5+
- `npm run build` - Build the TypeScript project using esbuild
6+
- `npm run release` - Build and publish to npm
7+
8+
## CLI Commands
9+
- `ccr start` - Start the router server
10+
- `ccr stop` - Stop the router server
11+
- `ccr restart` - Restart the router server
12+
- `ccr status` - Check server status
13+
- `ccr code "<prompt>"` - Run Claude Code through the router
14+
- `ccr ui` - Launch web UI for configuration management (beta)
15+
16+
## Configuration
17+
- Config file location: `~/.claude-code-router/config.json`
18+
- Edit config to add/modify providers and routing rules
19+
- Restart server after config changes: `ccr restart`
20+
21+
## Dynamic Model Switching (within Claude Code)
22+
- `/model provider_name,model_name` - Switch to specific model
23+
- Example: `/model openrouter,anthropic/claude-3.5-sonnet`
24+
25+
## System Commands (Linux)
26+
- `git` - Version control
27+
- `ls -la` - List files with details
28+
- `cd` - Change directory
29+
- `grep` - Search in files
30+
- `find` - Find files
31+
- `ps aux | grep ccr` - Check running processes
32+
- `tail -f ~/.claude-code-router.log` - Monitor logs (if logging enabled)
Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Task Completion Checklist
2+
3+
When completing development tasks on Claude Code Router:
4+
5+
## 1. Code Quality
6+
- [ ] TypeScript compiles without errors
7+
- [ ] No ESLint warnings (if configured)
8+
- [ ] Code follows project conventions
9+
10+
## 2. Testing
11+
- [ ] Test changes manually with `ccr` commands
12+
- [ ] Verify server starts/stops correctly
13+
- [ ] Test routing to different models
14+
- [ ] Check error handling scenarios
15+
16+
## 3. Build Verification
17+
- [ ] Run `npm run build` successfully
18+
- [ ] Check `dist/` folder contains compiled files
19+
- [ ] CLI commands work with built version
20+
21+
## 4. Configuration
22+
- [ ] Update config.example.json if adding new features
23+
- [ ] Document new config options in README
24+
- [ ] Ensure backward compatibility
25+
26+
## 5. Documentation
27+
- [ ] Update README.md for new features
28+
- [ ] Update CLAUDE.md if changing architecture
29+
- [ ] Add inline comments for complex logic
30+
31+
## 6. Pre-commit
32+
- [ ] Stage relevant files with `git add`
33+
- [ ] Write clear commit message
34+
- [ ] Consider version bump if needed

.serena/project.yml

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# language of the project (csharp, python, rust, java, typescript, go, cpp, or ruby)
2+
# * For C, use cpp
3+
# * For JavaScript, use typescript
4+
# Special requirements:
5+
# * csharp: Requires the presence of a .sln file in the project folder.
6+
language: typescript
7+
8+
# whether to use the project's gitignore file to ignore files
9+
# Added on 2025-04-07
10+
ignore_all_files_in_gitignore: true
11+
# list of additional paths to ignore
12+
# same syntax as gitignore, so you can use * and **
13+
# Was previously called `ignored_dirs`, please update your config if you are using that.
14+
# Added (renamed)on 2025-04-07
15+
ignored_paths: []
16+
17+
# whether the project is in read-only mode
18+
# If set to true, all editing tools will be disabled and attempts to use them will result in an error
19+
# Added on 2025-04-18
20+
read_only: false
21+
22+
23+
# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
24+
# Below is the complete list of tools for convenience.
25+
# To make sure you have the latest list of tools, and to view their descriptions,
26+
# execute `uv run scripts/print_tool_overview.py`.
27+
#
28+
# * `activate_project`: Activates a project by name.
29+
# * `check_onboarding_performed`: Checks whether project onboarding was already performed.
30+
# * `create_text_file`: Creates/overwrites a file in the project directory.
31+
# * `delete_lines`: Deletes a range of lines within a file.
32+
# * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
33+
# * `execute_shell_command`: Executes a shell command.
34+
# * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
35+
# * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
36+
# * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
37+
# * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
38+
# * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file or directory.
39+
# * `initial_instructions`: Gets the initial instructions for the current project.
40+
# Should only be used in settings where the system prompt cannot be set,
41+
# e.g. in clients you have no control over, like Claude Desktop.
42+
# * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
43+
# * `insert_at_line`: Inserts content at a given line in a file.
44+
# * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
45+
# * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
46+
# * `list_memories`: Lists memories in Serena's project-specific memory store.
47+
# * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
48+
# * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
49+
# * `read_file`: Reads a file within the project directory.
50+
# * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
51+
# * `remove_project`: Removes a project from the Serena configuration.
52+
# * `replace_lines`: Replaces a range of lines within a file with new content.
53+
# * `replace_symbol_body`: Replaces the full definition of a symbol.
54+
# * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
55+
# * `search_for_pattern`: Performs a search for a pattern in the project.
56+
# * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
57+
# * `switch_modes`: Activates modes by providing a list of their names
58+
# * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
59+
# * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
60+
# * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
61+
# * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
62+
excluded_tools: []
63+
64+
# initial prompt for the project. It will always be given to the LLM upon activating the project
65+
# (contrary to the memories, which are loaded on demand).
66+
initial_prompt: ""
67+
68+
project_name: "claude-code-router"

0 commit comments

Comments
 (0)