Skip to content

Commit 447e461

Browse files
thedotmackthedotmack
authored
Merge pull request winfunc#7 from thedotmack/copilot/fix-6
Add standalone TypeScript server for Claude Code integration
2 parents 29e85c6 + 9b15063 commit 447e461

26 files changed

Lines changed: 13758 additions & 0 deletions

‎CLAUDIA-SERVER.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# Claudia Server - TypeScript Implementation
2+
3+
This directory contains a complete standalone TypeScript server implementation of Claudia's Claude Code integration functionality.
4+
5+
## What is Claudia Server?
6+
7+
Claudia Server extracts the core Claude Code CLI wrapper functionality from the original Claudia desktop application and provides it as a standalone TypeScript/Node.js HTTP and WebSocket server. This allows you to integrate Claude Code into any application using standard web protocols.
8+
9+
## Key Benefits
10+
11+
- **Language Agnostic**: Use any programming language that can make HTTP requests
12+
- **Standalone**: No desktop app required, runs as a service
13+
- **Real-time**: WebSocket streaming for live Claude responses
14+
- **Lightweight**: Pure TypeScript/Node.js implementation
15+
- **API-First**: RESTful API design with comprehensive documentation
16+
- **Cross-platform**: Works on Windows, macOS, and Linux
17+
18+
## Quick Start
19+
20+
```bash
21+
cd claudia-server
22+
npm install
23+
npm run build
24+
npm start
25+
```
26+
27+
The server will start on `http://localhost:3000` with WebSocket support at `ws://localhost:3000/ws`.
28+
29+
## Documentation
30+
31+
- **[README.md](README.md)** - Complete API documentation
32+
- **[QUICKSTART.md](QUICKSTART.md)** - Quick start guide
33+
- **[examples/](examples/)** - Client examples in multiple languages
34+
35+
## Architecture
36+
37+
The server implements the same functionality as the Rust/Tauri backend:
38+
39+
```
40+
┌─────────────────┐ HTTP/WS ┌─────────────────┐ CLI ┌─────────────────┐
41+
│ Your Client │ ────────────► │ Claudia Server │ ─────────► │ Claude Code │
42+
│ (Any Language) │ │ (TypeScript) │ │ CLI │
43+
└─────────────────┘ └─────────────────┘ └─────────────────┘
44+
```
45+
46+
## Features Implemented
47+
48+
✅ Claude Code CLI integration with auto-discovery
49+
✅ Real-time streaming via WebSocket
50+
✅ Project and session management
51+
✅ CLAUDE.md file operations
52+
✅ Process management and monitoring
53+
✅ Health checks and server status
54+
✅ Comprehensive error handling
55+
✅ CORS and security middleware
56+
✅ Complete API documentation
57+
✅ Multiple client examples
58+
59+
## API Endpoints
60+
61+
| Endpoint | Method | Description |
62+
|----------------------------------|-----------|--------------------------------|
63+
| `/api/status/health` | GET | Server health check |
64+
| `/api/status/info` | GET | Server info/config summary |
65+
| `/api/claude/version` | GET | Claude CLI version |
66+
| `/api/claude/execute` | POST | Start new Claude session |
67+
| `/api/claude/continue` | POST | Continue an existing session |
68+
| `/api/claude/resume` | POST | Resume a paused session |
69+
| `/api/claude/cancel/{id}` | POST | Cancel a running session |
70+
| `/api/claude/sessions/running` | GET | List running sessions |
71+
| `/api/projects` | GET | List all projects |
72+
| `/api/projects` | POST | Create a new project |
73+
| `/ws` | WebSocket | Real-time streaming |
74+
75+
See [README.md](README.md) for complete API documentation.
76+
77+
## Client Examples
78+
79+
### JavaScript
80+
```javascript
81+
const response = await fetch('http://localhost:3000/api/claude/execute', {
82+
method: 'POST',
83+
headers: { 'Content-Type': 'application/json' },
84+
body: JSON.stringify({
85+
project_path: '/path/to/project',
86+
prompt: 'Help me code',
87+
model: 'claude-3-5-sonnet-20241022'
88+
})
89+
});
90+
```
91+
92+
### Python
93+
```python
94+
import aiohttp
95+
96+
async with aiohttp.ClientSession() as session:
97+
async with session.post('http://localhost:3000/api/claude/execute',
98+
json={'project_path': '/path', 'prompt': 'Help me'}) as resp:
99+
result = await resp.json()
100+
```
101+
102+
### curl
103+
```bash
104+
curl -X POST http://localhost:3000/api/claude/execute \
105+
-H "Content-Type: application/json" \
106+
-d '{"project_path": "/path", "prompt": "Help me", "model": "claude-3-5-sonnet-20241022"}'
107+
```
108+
109+
## Use Cases
110+
111+
- **Web Applications**: Integrate Claude Code into web apps
112+
- **Mobile Apps**: Use from iOS/Android via HTTP API
113+
- **CI/CD Pipelines**: Automated code analysis and generation
114+
- **IDEs/Editors**: Custom editor integrations
115+
- **Microservices**: Claude Code as a microservice
116+
- **Chatbots**: Build Claude-powered chatbots
117+
- **API Gateways**: Proxy Claude functionality
118+
119+
## Deployment
120+
121+
The server can be deployed anywhere Node.js runs:
122+
123+
- **Local Development**: `npm start`
124+
- **Production**: PM2, Docker, Kubernetes
125+
- **Cloud**: AWS, GCP, Azure, Heroku
126+
- **Edge**: Vercel, Netlify Functions
127+
128+
## Comparison with Desktop App
129+
130+
| Feature | Desktop App | TypeScript Server |
131+
|---------|-------------|-------------------|
132+
| **Interface** | GUI (Tauri/React) | HTTP/WebSocket API |
133+
| **Language** | Rust + TypeScript | Pure TypeScript |
134+
| **Deployment** | Desktop installation | Web service |
135+
| **Integration** | Standalone app | API for any client |
136+
| **Scalability** | Single user | Multi-user capable |
137+
| **Platform** | Desktop platforms | Any HTTP client |
138+
139+
## Getting Started
140+
141+
1. **Install dependencies**: `npm install`
142+
2. **Build the project**: `npm run build`
143+
3. **Start the server**: `npm start`
144+
4. **Test the API**: `curl http://localhost:3000/api/status/health`
145+
5. **Try examples**: See `examples/` directory
146+
147+
For detailed setup and usage instructions, see [QUICKSTART.md](QUICKSTART.md).
148+
149+
---
150+
151+
This TypeScript server provides the same powerful Claude Code integration as the desktop app, but as a flexible web service that can be integrated into any application or workflow.

‎claudia-server/.eslintrc.js‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
module.exports = {
2+
parser: '@typescript-eslint/parser',
3+
parserOptions: {
4+
ecmaVersion: 2022,
5+
sourceType: 'module',
6+
},
7+
plugins: ['@typescript-eslint'],
8+
extends: [
9+
'eslint:recommended',
10+
'@typescript-eslint/recommended',
11+
],
12+
rules: {
13+
'@typescript-eslint/no-unused-vars': 'error',
14+
'@typescript-eslint/no-explicit-any': 'warn',
15+
'@typescript-eslint/explicit-function-return-type': 'off',
16+
'@typescript-eslint/explicit-module-boundary-types': 'off',
17+
'@typescript-eslint/no-empty-function': 'warn',
18+
},
19+
env: {
20+
node: true,
21+
es6: true,
22+
jest: true,
23+
},
24+
};

‎claudia-server/.gitignore‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
node_modules/
2+
dist/
3+
.env
4+
.env.local
5+
.env.*.local
6+
logs/
7+
*.log
8+
npm-debug.log*
9+
yarn-debug.log*
10+
yarn-error.log*
11+
.DS_Store
12+
.vscode/
13+
.idea/
14+
*.swp
15+
*.swo
16+
*~
17+
coverage/
18+
.nyc_output/
19+
.tmp/
20+
.cache/

‎claudia-server/.prettierrc‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"semi": true,
3+
"trailingComma": "es5",
4+
"singleQuote": true,
5+
"printWidth": 100,
6+
"tabWidth": 2,
7+
"useTabs": false
8+
}

0 commit comments

Comments
 (0)