claudia-server/.gitignore (5)

6-10: Include pnpm debug logs alongside npm/yarn.

You already ignore npm and yarn debug logs; add pnpm parity.

Apply this diff:

 *.log
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+pnpm-debug.log*

---

1-2: Ignore TypeScript incremental build info files.

tsc can emit .tsbuildinfo; safe to ignore.

Apply this diff:

 node_modules/
 dist/
+*.tsbuildinfo

---

19-20: Add common linter cache file to reduce churn.

ESLint may create a cache file; ignore it.

Apply this diff:

 .tmp/
 .cache/
+.eslintcache

---

11-11: Optionally add Windows thumbnail cache.

Avoid committing Windows-specific metadata.

Apply this diff:

 .DS_Store
+Thumbs.db

---

19-20: Also ignore non-dot tmp directory.

Some tooling uses tmp/ instead of .tmp/.

Apply this diff:

 .tmp/
+.tmp/
+.cache/
+tmp/

Note: If the duplicate .tmp/ line above already exists, keep a single occurrence; the intent is to add tmp/.

claudia-server/.prettierrc (1)

1-8: Add explicit end-of-line setting to avoid cross-OS diffs

Windows contributors may otherwise generate CRLF/LF churn. Prefer auto to respect existing file endings.

Apply this diff:

 {
   "semi": true,
   "trailingComma": "es5",
   "singleQuote": true,
   "printWidth": 100,
   "tabWidth": 2,
-  "useTabs": false
+  "useTabs": false,
+  "endOfLine": "auto"
 }

claudia-server/package.json (3)

10-19: Broaden format coverage and add fix script

Formatting only src/**/*.ts misses docs, JSON, and configs. Also handy to include a lint autofix script.

Apply this diff:

   "scripts": {
     "dev": "tsx watch src/index.ts",
     "build": "tsc",
     "start": "node dist/index.js",
     "cli": "node dist/cli.js",
     "test": "jest",
     "lint": "eslint src --ext .ts",
-    "format": "prettier --write src/**/*.ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "format": "prettier --write .",
     "clean": "rm -rf dist"
   },

---

44-63: Avoid ESLint/Prettier rule conflicts

Include eslint-config-prettier and extend it to turn off stylistic rules that conflict with Prettier.

Apply this diff to devDependencies:

   "devDependencies": {
     "@types/compression": "^1.7.5",
     "@types/cors": "^2.8.16",
     "@types/express": "^4.17.21",
     "@types/jest": "^29.5.7",
     "@types/morgan": "^1.9.9",
     "@types/node": "^20.8.0",
     "@types/node-cron": "^3.0.11",
     "@types/sqlite3": "^3.1.11",
     "@types/uuid": "^9.0.7",
     "@types/ws": "^8.5.8",
     "@typescript-eslint/eslint-plugin": "^6.9.0",
     "@typescript-eslint/parser": "^6.9.0",
     "eslint": "^8.52.0",
     "jest": "^29.7.0",
     "prettier": "^3.0.3",
+    "eslint-config-prettier": "^9.0.0",
     "ts-jest": "^29.1.1",
     "tsx": "^3.14.0",
     "typescript": "^5.2.2"
   },

---

28-31: Optional: Define published files to avoid shipping sources by accident

If you intend to publish, restrict package contents. If not, set "private": true instead.

Add a files whitelist (or confirm "private": true):

   "author": "Claudia Project",
   "license": "AGPL-3.0",
+  "files": [
+    "dist/",
+    "README.md",
+    "CLAUDIA-SERVER.md",
+    "QUICKSTART.md",
+    "LICENSE"
+  ],

claudia-server/tsconfig.json (2)

13-24: Prefer verbatim module syntax and drop decorators unless needed

verbatimModuleSyntax improves ESM correctness; experimentalDecorators/emitDecoratorMetadata add overhead and aren’t typically needed for Express servers.

Apply this diff:

     "resolveJsonModule": true,
     "allowSyntheticDefaultImports": true,
+    "verbatimModuleSyntax": true,
     "declaration": true,
     "declarationMap": true,
     "sourceMap": true,
     "removeComments": false,
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true,
+    "experimentalDecorators": false,
+    "emitDecoratorMetadata": false,
     "allowImportingTsExtensions": false,
     "noEmit": false,
     "types": ["node", "jest"]

---

25-27: Consider separate tsconfigs for app vs tests

Including jest types in the main tsconfig can leak test globals into app type-checking. A tsconfig.build.json (without jest) plus tsconfig.test.json is cleaner.

CLAUDIA-SERVER.md (3)

20-27: Mention configuration options (env vars and CLI flags)

Document PORT, CORS origins, Claude binary path discovery, and any CLI flags to improve operability.

Happy to draft a “Configuration” section if you share the intended env vars/flags.

---

117-121: Qualify “Edge” deployment claim

Express + ws typically won’t run on serverless edge runtimes (e.g., Netlify/Vercel Edge) without adapters, and WebSockets may be unsupported. Consider qualifying or linking to guidance.

---

73-84: API request fields use snake_case; example is correct

Confirmed that all Claude request interfaces (ExecuteClaudeRequest, ContinueClaudeRequest, ResumeClaudeRequest) define their fields in snake_case (e.g. project_path, session_id), so the snippet’s payload matches the API contract. The model property is accepted as an open string (no enum enforced), so your example with "claude-3-5-sonnet-20241022" is valid.

Optional: You may consider introducing an enum or documenting the set of supported model identifiers for compile-time safety and clearer developer guidance.

claudia-server/.eslintrc.js (4)

1-7: Mark config as project root and ignore build artifacts

Prevents config cascading and speeds lint by skipping dist/.

Apply this diff:

-module.exports = {
+module.exports = {
+  root: true,
   parser: '@typescript-eslint/parser',
   parserOptions: {
     ecmaVersion: 2022,
     sourceType: 'module',
   },
+  ignorePatterns: ['dist/', 'node_modules/'],

---

8-11: Extend Prettier to avoid stylistic conflicts

Disable conflicting ESLint rules by extending prettier.

Apply this diff:

   extends: [
     'eslint:recommended',
     '@typescript-eslint/recommended',
+    'prettier',
   ],

---

12-18: Tweak no-unused-vars to allow intentionally unused placeholders

Common for Express handlers (req, _res, _next) and event callbacks.

Apply this diff:

   rules: {
-    '@typescript-eslint/no-unused-vars': 'error',
+    '@typescript-eslint/no-unused-vars': ['error', {
+      "argsIgnorePattern": "^_",
+      "varsIgnorePattern": "^_",
+      "caughtErrorsIgnorePattern": "^_"
+    }],
     '@typescript-eslint/no-explicit-any': 'warn',
     '@typescript-eslint/explicit-function-return-type': 'off',
     '@typescript-eslint/explicit-module-boundary-types': 'off',
     '@typescript-eslint/no-empty-function': 'warn',
   },

---

19-23: Limit Jest globals to tests via overrides (optional)

Keeps app files free of test globals, while still enabling them for *.test.ts.

Example override:

   env: {
     node: true,
     es6: true,
-    jest: true,
   },
+  overrides: [
+    {
+      files: ['**/*.test.ts'],
+      env: { jest: true }
+    }
+  ],

claudia-server/examples/curl/api-examples.sh (2)

42-48: Consider using a more portable approach for JSON construction.

While the current heredoc-style JSON works, it could be more portable and less error-prone:

-SESSION_RESPONSE=$(curl -s -X POST "$SERVER_URL/api/claude/execute" \
-  -H "Content-Type: application/json" \
-  -d "{
-    \"project_path\": \"$PROJECT_PATH\",
-    \"prompt\": \"Help me understand this project structure\",
-    \"model\": \"claude-3-5-sonnet-20241022\"
-  }")
+SESSION_RESPONSE=$(curl -s -X POST "$SERVER_URL/api/claude/execute" \
+  -H "Content-Type: application/json" \
+  -d "$(jq -n --arg project_path "$PROJECT_PATH" \
+             --arg prompt "Help me understand this project structure" \
+             --arg model "claude-3-5-sonnet-20241022" \
+             '{project_path: $project_path, prompt: $prompt, model: $model}')")

This approach handles special characters in paths more safely and avoids potential JSON injection issues.

---

70-70: Consider adding error handling for the history truncation.

The current approach using head -c 500 could potentially cut off in the middle of a multibyte character. Consider using a safer approach:

-  curl -s "$SERVER_URL/api/claude/sessions/$SESSION_ID/history" | jq -r '.data.history' | head -c 500
+  HISTORY=$(curl -s "$SERVER_URL/api/claude/sessions/$SESSION_ID/history" | jq -r '.data.history // ""')
+  echo "${HISTORY:0:500}"

This bash parameter expansion approach is safer for handling potentially complex Unicode content.

claudia-server/test.sh (1)

77-81: Consider improving WebSocket test robustness.

The current WebSocket test is quite basic and might not catch actual WebSocket functionality issues:

-if command -v wscat >/dev/null 2>&1; then
-    echo '{"type":"status"}' | timeout 2s wscat -c "ws://localhost:$SERVER_PORT/ws" >/dev/null 2>&1 && echo "   WebSocket endpoint accessible ✓" || echo "   WebSocket test skipped (connection failed)"
-else
-    echo "   WebSocket test skipped (wscat not available)"
-fi
+if command -v wscat >/dev/null 2>&1; then
+    WS_OUTPUT=$(timeout 5s wscat -c "ws://localhost:$SERVER_PORT/ws" -x '{"type":"status"}' 2>/dev/null || echo "FAILED")
+    if [[ "$WS_OUTPUT" == *"status"* ]] || [[ "$WS_OUTPUT" == *"connected"* ]]; then
+        echo "   WebSocket endpoint working ✓"
+    else
+        echo "   WebSocket test failed (no proper response)"
+    fi
+else
+    echo "   WebSocket test skipped (wscat not available)"
+fi

This tests for an actual WebSocket response rather than just connection success.

claudia-server/src/cli.ts (1)

78-96: Consider adding type safety for API responses.

The CLI uses as any for API responses, which bypasses TypeScript's type checking. Consider defining proper interfaces:

interface HealthResponse {
  success: boolean;
  data: {
    status: string;
    uptime: number;
    memory: {
      heapUsed: number;
    };
  };
}

Then use:

-      const result = await response.json() as any;
+      const result = await response.json() as HealthResponse;

This would provide better type safety and catch potential API contract changes at compile time.

claudia-server/QUICKSTART.md (1)

170-192: Nginx config: quote consistency and minor proxy hardening.

• Use consistent quoting for the “Connection” header.
• Consider adding proxy_read_timeout for WS blocks to avoid idle disconnects in some setups.

Apply this small fix to quoting in the first location block:

         proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection 'upgrade';
+        proxy_set_header Connection "upgrade";

Optionally, add this in both location / and location /ws blocks:

proxy_read_timeout 600s;

claudia-server/examples/javascript/client.js (1)

38-41: Harden error handling when non-JSON errors are returned.

On non-OK responses, response.json() may itself throw. Provide a safe fallback to response.text().

Apply these diffs:

-    if (!response.ok) {
-      const error = await response.json();
-      throw new Error(`Failed to start session: ${error.error}`);
-    }
+    if (!response.ok) {
+      let errorMessage = `${response.status} ${response.statusText}`;
+      try {
+        const error = await response.json();
+        errorMessage = error.error || JSON.stringify(error);
+      } catch {
+        try { errorMessage = await response.text(); } catch {}
+      }
+      throw new Error(`Failed to start session: ${errorMessage}`);
+    }

-    if (!response.ok) {
-      const error = await response.json();
-      throw new Error(`Failed to get running sessions: ${error.error}`);
-    }
+    if (!response.ok) {
+      let errorMessage = `${response.status} ${response.statusText}`;
+      try {
+        const error = await response.json();
+        errorMessage = error.error || JSON.stringify(error);
+      } catch {
+        try { errorMessage = await response.text(); } catch {}
+      }
+      throw new Error(`Failed to get running sessions: ${errorMessage}`);
+    }

-    if (!response.ok) {
-      const error = await response.json();
-      throw new Error(`Failed to cancel session: ${error.error}`);
-    }
+    if (!response.ok) {
+      let errorMessage = `${response.status} ${response.statusText}`;
+      try {
+        const error = await response.json();
+        errorMessage = error.error || JSON.stringify(error);
+      } catch {
+        try { errorMessage = await response.text(); } catch {}
+      }
+      throw new Error(`Failed to cancel session: ${errorMessage}`);
+    }

Also applies to: 143-146, 160-163

claudia-server/examples/python/client.py (2)

20-20: Remove unused import.

Optional isn’t used.

Apply this diff:

-from typing import Optional

---

147-150: Remove unused variable assignment.

health is assigned but not used.

Apply this diff:

-            health = await client.check_health()
-            print("✅ Server is healthy")
+            await client.check_health()
+            print("✅ Server is healthy")

claudia-server/src/index.ts (2)

49-51: Avoid hardcoding version. Read it from environment or package metadata.

Printing a fixed version will drift. Use npm_package_version as a lightweight improvement.

Apply this diff:

-      case '--version':
-        console.log('1.0.0');
+      case '--version':
+        console.log(process.env.npm_package_version ?? 'unknown');

---

26-31: Short flag ‘-h’ commonly maps to help, not host. Consider using ‘-H’ for host.

Potential UX confusion: -h is widely understood as help. If you want to keep -h for host, maybe also add -? or --help alias messaging. Optional.

claudia-server/src/routes/status.ts (2)

31-37: Avoid hardcoding app version; use environment or package metadata.

The /info endpoint returns a fixed "1.0.0", which will drift.

Apply this diff:

-        version: '1.0.0',
+        version: process.env.npm_package_version ?? 'unknown',

---

42-43: Reflect configured CLAUDE home if set.

Use process.env.CLAUDE_HOME when available; otherwise default to ~/.claude. This aligns with the CLI and docs.

Apply this diff:

-        claude_home: join(homedir(), '.claude'),
+        claude_home: process.env.CLAUDE_HOME || join(homedir(), '.claude'),

-        home_directory: homedir(),
-        claude_directory: join(homedir(), '.claude'),
+        home_directory: homedir(),
+        claude_directory: process.env.CLAUDE_HOME || join(homedir(), '.claude'),

Also applies to: 57-59

claudia-server/src/server.ts (2)

74-77: Consider making request timeout configurable.

The request timeout is hard-coded to 30 seconds. This should be configurable through the ServerConfig to allow flexibility for different deployment scenarios.

Add timeout configuration to the ServerConfig:

-    // Request timeout
-    this.app.use((req, res, next) => {
-      req.setTimeout(30000); // 30 seconds
-      next();
-    });
+    // Request timeout
+    const timeout = this.config.request_timeout_ms || 30000;
+    this.app.use((req, res, next) => {
+      req.setTimeout(timeout);
+      next();
+    });

Also update the ServerConfig interface in claudia-server/src/types/index.ts:

export interface ServerConfig {
  port: number;
  host: string;
  cors_origin: string[];
  max_concurrent_sessions: number;
  session_timeout_ms: number;
  request_timeout_ms?: number; // Add this field
  claude_binary_path?: string;
  claude_home_dir?: string;
}

---

164-173: Process termination on uncaught exceptions/rejections may be too aggressive.

Terminating the process immediately on uncaught exceptions or unhandled rejections could lead to abrupt service interruptions. Consider logging the error and allowing the process to continue for less critical errors, or implementing a graceful degradation strategy.

Consider implementing a more nuanced error handling strategy:

    // Handle uncaught exceptions
    process.on('uncaughtException', (error) => {
      console.error('Uncaught Exception:', error);
-      this.gracefulShutdown('UNCAUGHT_EXCEPTION');
+      // Only shutdown for critical errors
+      if (this.isCriticalError(error)) {
+        this.gracefulShutdown('UNCAUGHT_EXCEPTION');
+      }
    });

    // Handle unhandled rejections
    process.on('unhandledRejection', (reason, promise) => {
      console.error('Unhandled Rejection at:', promise, 'reason:', reason);
-      this.gracefulShutdown('UNHANDLED_REJECTION');
+      // Log but don't necessarily shutdown
+      // Consider implementing a counter for repeated rejections
    });

Add a helper method to determine critical errors:

private isCriticalError(error: Error): boolean {
  // Define what constitutes a critical error
  // e.g., database connection errors, file system errors, etc.
  return error.message.includes('ENOENT') || 
         error.message.includes('EACCES') ||
         error.message.includes('EMFILE');
}

claudia-server/src/services/websocket.ts (2)

63-64: Consider using a more robust ID generation method.

The current client ID generation could theoretically produce collisions in high-concurrency scenarios. Consider using a UUID library for guaranteed uniqueness.

+import { v4 as uuidv4 } from 'uuid';
+
  private generateClientId(): string {
-    return `client_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    return `client_${uuidv4()}`;
  }

---

130-136: Consider adding WebSocket.CONNECTING state check.

The client state check only verifies WebSocket.OPEN, but should also handle the CONNECTING state appropriately.

  private sendToClient(clientId: string, message: WebSocketMessage): void {
    const client = this.clients.get(clientId);
-    if (client && client.readyState === WebSocket.OPEN) {
+    if (client) {
+      if (client.readyState === WebSocket.OPEN) {
        try {
          client.send(JSON.stringify(message));
        } catch (error) {
          console.error(`Failed to send message to client ${clientId}:`, error);
        }
+      } else if (client.readyState === WebSocket.CONNECTING) {
+        // Queue message or wait for connection
+        console.warn(`Client ${clientId} still connecting, message dropped`);
+      }
    }
  }

claudia-server/src/services/project.ts (6)

99-101: Use birthtime (if available) instead of ctime for created_at

ctime is inode change time, not creation time. Prefer birthtime with fallback to mtime for portability.

Apply this diff:

-      created_at: Math.floor(stats.ctime.getTime() / 1000),
+      created_at: Math.floor(((stats.birthtime?.getTime?.() ?? 0) || stats.mtime.getTime()) / 1000),

---

254-254: Use birthtime (if available) for session created_at instead of ctime

Align with creation semantics for more stable sorting.

Apply this diff:

-      created_at: Math.floor(stats.ctime.getTime() / 1000),
+      created_at: Math.floor(((stats.birthtime?.getTime?.() ?? 0) || stats.mtime.getTime()) / 1000),

---

107-130: Avoid reading entire JSONL files to discover the first line/cwd

Both performance and memory can suffer on large session files. Read only the first line (or a small prefix) instead of the full file.

Example replacement using fs.open to read a small chunk:

// inside getProjectPathFromSessions
const filePath = join(projectDir, entry.name);
const fh = await fs.open(filePath, 'r');
try {
  const buf = Buffer.alloc(8192);
  const { bytesRead } = await fh.read(buf, 0, buf.length, 0);
  const nl = buf.indexOf(10); // '\n'
  const json = buf.subarray(0, nl > -1 ? nl : bytesRead).toString('utf-8').trim();
  if (json) {
    const firstLine = JSON.parse(json);
    if (firstLine.cwd) return firstLine.cwd;
  }
} finally {
  await fh.close();
}

---

300-330: Exclude heavy/common vendor directories when scanning for CLAUDE.md

This scan can become expensive. Consider skipping node_modules, .git, dist, build, target by default.

Apply this diff:

-      for (const entry of entries) {
+      const excluded = new Set(['.git', 'node_modules', 'dist', 'build', 'target']);
+      for (const entry of entries) {
         const fullPath = join(currentPath, entry.name);
         
-        if (entry.isDirectory() && !entry.name.startsWith('.')) {
+        if (entry.isDirectory() && !entry.name.startsWith('.') && !excluded.has(entry.name)) {

---

364-365: Normalize empty extension to undefined

Avoid returning empty string for files like "Makefile" or "file.".

Apply this diff:

-          extension: entry.isDirectory() ? undefined : extname(entry.name).substring(1),
+          extension: entry.isDirectory() ? undefined : (extname(entry.name).slice(1) || undefined),

---

264-280: loadSessionHistory scans all projects eagerly; consider a fast path

Calling listProjects() builds session lists for every project, which is heavy. A faster approach is to iterate project directories and check for the session file existence directly, stopping at the first hit.

I can provide a focused patch if you want to switch to a direct existence check to reduce IO.

claudia-server/src/types/index.ts (1)

59-61: Narrow loosely-typed fields (any) to improve safety and discoverability

Where possible, prefer unknown or concrete interfaces over any for:

• ClaudeSettings index signature
• Session.todo_data
• ClaudeStreamMessage.tool_calls
• ErrorResponse.details

Suggested changes:

• Define minimal shapes:

  • type Json = string | number | boolean | null | Json[] | { [k: string]: Json };
  • export type TodoData = Json;
  • export type ToolCall = { name: string; arguments: Json; [k: string]: unknown };

• Apply:

  • ClaudeSettings: Record<string, Json>
  • Session.todo_data?: TodoData
  • ClaudeStreamMessage.tool_calls?: ToolCall[]
  • ErrorResponse.details?: Json

Also applies to: 112-113, 47-47, 169-170

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.