@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

$3

`typescript
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);
`

$3

`typescript
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 |

$3

`typescript
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 |