@codmir/agent

Core agent logic for Codmir - reusable in IDE (local) and cloud (remote) modes.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        @codmir/agent                             │
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐   │
│  │   Session    │  │    Tools     │  │     AI Client        │   │
│  │   Manager    │  │   Executor   │  │   (Streaming)        │   │
│  └──────────────┘  └──────────────┘  └──────────────────────┘   │
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐   │
│  │   Context    │  │    Tool      │  │     Approval         │   │
│  │   Provider   │  │  Definitions │  │     Handler          │   │
│  └──────────────┘  └──────────────┘  └──────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
        ┌──────────┐   ┌──────────┐   ┌──────────────┐
        │   IDE    │   │  Cloud   │   │   Claude     │
        │  (local) │   │ (remote) │   │   Code API   │
        └──────────┘   └──────────┘   └──────────────┘

Modes

Local Mode (IDE)

• Session runs on user's machine
• Connection active while IDE is open
• Session ends when IDE closes
• Faster response (no network latency for tools)

Cloud Mode (Remote)

• Session runs on Codmir servers
• User can close IDE, session persists
• Session continues in background
• Results synced when user reconnects

Usage

In IDE (Local Mode)

import { createAgent, LocalSessionManager } from '@codmir/agent';
import { FileSystemAdapter } from './adapters/filesystem';

const agent = createAgent({
  mode: 'local',
  sessionManager: new LocalSessionManager(),
  contextProvider: new FileSystemAdapter(workspaceRoot),
  aiConfig: {
    provider: 'codmir', // or 'openai', 'anthropic'
    apiKey: process.env.CODMIR_API_KEY,
  },
});

// Start a session
const session = await agent.createSession({
  prompt: 'Fix the bug in auth.ts',
});

// Listen to events
agent.on('thinking', (data) => updateUI('thinking', data));
agent.on('tool_call', (data) => showToolCall(data));
agent.on('response_chunk', (data) => appendToChat(data));
agent.on('complete', (data) => finalizeResponse(data));

// Approve tool calls
await agent.approveToolCall(session.id, toolCallId);

In Cloud (Remote Mode)

import { createAgent, CloudSessionManager } from '@codmir/agent';
import { RemoteFileAdapter } from './adapters/remote';

const agent = createAgent({
  mode: 'cloud',
  sessionManager: new CloudSessionManager({
    redis: redisClient,
    persistSessions: true,
  }),
  contextProvider: new RemoteFileAdapter(ideConnection),
  aiConfig: {
    provider: 'codmir',
    apiKey: process.env.CODMIR_API_KEY,
  },
});

// Session persists even if client disconnects
const session = await agent.resumeSession(sessionId);

Tools

Built-in tools available to the agent:

| Tool | Description | |------|-------------| | read_file | Read file contents | | write_file | Write/create file | | edit_file | Apply targeted edits | | list_directory | List files in directory | | search_files | Search for text in files | | run_command | Execute terminal command | | git_status | Get git status | | git_diff | Get git diff | | ask_user | Ask user a question |

Custom Tools

import { defineTool } from '@codmir/agent/tools';

const myTool = defineTool({
  name: 'my_custom_tool',
  description: 'Does something custom',
  parameters: z.object({
    input: z.string(),
  }),
  execute: async (params, context) => {
    // Your logic here
    return { result: 'done' };
  },
});

agent.registerTool(myTool);

Session Lifecycle

User Input
    │
    ▼
┌─────────────────┐
│ Create Session  │ ◄─── New conversation
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   AI Thinking   │ ◄─── Streaming response
└────────┬────────┘
         │
         ▼
┌─────────────────┐     ┌─────────────────┐
│   Tool Call?    │────►│ Execute Tool    │
└────────┬────────┘     └────────┬────────┘
         │                       │
         │◄──────────────────────┘
         ▼
┌─────────────────┐
│    Response     │ ◄─── Final answer
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Session Active  │ ◄─── Ready for next message
└─────────────────┘
         │
    Local: closes with IDE
    Cloud: persists until timeout

Events

| Event | Description | |-------|-------------| | session_created | New session started | | thinking_started | AI is processing | | response_chunk | Streaming text chunk | | tool_call_created | AI wants to use a tool | | tool_call_approved | User approved tool | | tool_call_rejected | User rejected tool | | tool_call_started | Tool execution began | | tool_call_completed | Tool finished successfully | | tool_call_failed | Tool execution failed | | response_complete | Full response ready | | session_error | Error occurred | | session_ended | Session terminated |