Governor system for auditing code changes with AI reasoning, conversation history, and execution logs
npm install @codmir/governorGovernor system for auditing code changes with full AI context.
Governor is different from a traditional PR review:
| Traditional PR | Governor Audit |
|----------------|----------------|
| Code changes only | Code + AI reasoning + conversation + logs |
| Reviewer guesses intent | Intent is documented |
| Post-hoc review | Present during development |
| Manual review | AI-assisted analysis |
Governor = Present during each process (proactive)
Overseer = Reviews after completion (reactive)
- Audit Changes: Analyze code changes between any two commits
- Full Context: Include conversation history, AI reasoning, execution logs
- AI Analysis: Claude-powered review finding security, performance, logic issues
- Session Tracking: Monitor work as it happens, not just after
- CLI Support: Quick audits from command line
- Tool Integration: Register audit tools with AI agents
``bash`
pnpm add @codmir/governor
`bashAudit recent changes
codmir-agent audit
$3
typescript
import { createAuditService, createGovernorSession } from '@codmir/governor';// Create audit service
const auditService = createAuditService({
repoPath: '/path/to/repo',
apiKey: process.env.ANTHROPIC_API_KEY,
});
// Quick audit
const audit = await auditService.quickAudit({
from: 'HEAD~10',
to: 'HEAD',
});
console.log('Findings:', audit.findings.length);
console.log('Recommendation:', audit.summary?.recommendation);
`$3
typescript
import { createGovernorSession, getGovernorSessionManager } from '@codmir/governor';// Start session when agent begins work
const session = createGovernorSession({
taskId: 'task-123',
baseCommit: 'abc123',
});
// Track conversation
const manager = getGovernorSessionManager();
manager.addConversationTurn(session.id, 'user', 'Please fix the login bug');
manager.addConversationTurn(session.id, 'assistant', 'I will fix the authentication issue...');
// Track reasoning
manager.addReasoning(session.id, {
target: { file: 'src/auth.ts', startLine: 42 },
intent: 'Fix null check on user token',
approach: 'Added optional chaining to prevent crash',
tradeoffs: ['Slightly less strict typing'],
});
// Track execution
manager.addLog(session.id, 'file_write', 'Modified src/auth.ts');
manager.addLog(session.id, 'command', 'npm test - all tests passing');
// Get context for audit
const context = manager.getContext(session.id);
`$3
typescript
import { AUDIT_TOOL_DEFINITIONS, createAuditToolExecutor } from '@codmir/governor';// Register tools with Claude
const tools = AUDIT_TOOL_DEFINITIONS;
// Execute tool calls
const executor = createAuditToolExecutor(auditService, {
agentId: 'agent-123',
agentName: 'Code Assistant',
});
const result = await executor.execute('audit_changes', {
from_commit: 'HEAD~5',
to_commit: 'HEAD',
min_severity: 'medium',
});
`Audit Lifecycle
Created → Analyzing → Reviewing → Approved/Rejected → Merged
1. Created: Audit record created with target commits
2. Analyzing: AI is analyzing changes
3. Reviewing: Analysis complete, awaiting human/agent review
4. Approved/Rejected: Decision made
5. Merged: Changes merged (optional tracking)
Finding Categories
-
- Security vulnerabilities
- performance - Performance issues
- logic - Logic errors or bugs
- style - Code style issues
- documentation - Missing/incorrect docs
- testing - Test coverage issues
- architecture - Architectural concerns
- dependency - Dependency issues
- compatibility - Compatibility problems
- accessibility - Accessibility issuesFinding Severities
-
critical - Must fix immediately
- high - Should fix before merge
- medium - Should fix soon
- low - Nice to fix
- info - Informational noteEvents
Subscribe to governor events:
`typescript
// governor.audit.created
// governor.audit.started
// governor.audit.completed
// governor.audit.failed
// governor.audit.approved
// governor.audit.rejected
// governor.audit.merged
// governor.finding.added
// governor.finding.resolved
// governor.context.updated
// governor.reasoning.added
``MIT