Code Tools

AgentOS provides 5 code tools for multi-language software development, including static analysis, formatting, linting, test execution, and AI-powered explanations.

Available Tools

code_analyze

Analyze code complexity metrics (lines, functions, classes).

filePath

string

required

Path to source file

path

string

Resolved absolute path

totalLines

number

Total lines in file

codeLines

number

Lines of code (excluding blank lines and comments)

blankLines

number

Number of blank lines

comments

number

Number of comment lines

functions

number

Function/method count

classes

number

Class count

extension

string

File extension (e.g., “.ts”, “.py”, “.rs”)

Example:

const result = await trigger("tool::code_analyze", {
  filePath: "src/tools.ts"
});

// => {
//   path: "/workspace/src/tools.ts",
//   totalLines: 606,
//   codeLines: 512,
//   blankLines: 48,
//   comments: 46,
//   functions: 22,
//   classes: 0,
//   extension: ".ts"
// }

Language Support:

TypeScript/JavaScript — Detects function, const fn = (), async function
Python — Detects def, async def, class
Rust — Generic pattern matching (future: tree-sitter AST parsing)

Implementation:

// src/tools-extended.ts:831-880
const functionPattern =
  ext === ".py"
    ? /^\s*(def|async\s+def)\s+\w+/
    : /^\s*(function|const\s+\w+\s*=\s*(async\s+)?\(|async\s+\w+\s*\(|export\s+(async\s+)?function)/;

const classPattern =
  ext === ".py" ? /^\s*class\s+\w+/ : /^\s*(class|export\s+class)\s+\w+/;

for (const line of lines) {
  const trimmed = line.trim();
  if (trimmed === "") blankLines++;
  else if (
    trimmed.startsWith("//") ||
    trimmed.startsWith("#") ||
    trimmed.startsWith("/*") ||
    trimmed.startsWith("*")
  )
    comments++;
  if (functionPattern.test(line)) functions++;
  if (classPattern.test(line)) classes++;
}

code_format

Format code using language-specific formatters.

filePath

string

required

Path to source file

formatter

string

Explicit formatter: "prettier", "black", "rustfmt" (auto-detected by extension)

formatted

boolean

true if formatting succeeded

path

string

Formatted file path

output

string

Formatter stdout/stderr output

Example:

const result = await trigger("tool::code_format", {
  filePath: "src/index.ts"
});

// => {
//   formatted: true,
//   path: "/workspace/src/index.ts",
//   output: "src/index.ts 42ms"
// }

Formatter Selection:

Extension	Formatter	Command
`.ts`, `.js`, `.json`, `.md`	Prettier	`npx prettier --write {file}`
`.py`	Black	`python3 -m black {file}`
`.rs`	rustfmt	`rustfmt {file}`

Requirements:

Prettier — Installed via npm install -D prettier
Black — Installed via pip install black
rustfmt — Included with Rust toolchain (rustup component add rustfmt)

Implementation:

// src/tools-extended.ts:883-923
let cmd: string;
let args: string[];

if (formatter === "rustfmt" || ext === ".rs") {
  cmd = "rustfmt";
  args = [resolved];
} else if (formatter === "black" || ext === ".py") {
  cmd = "python3";
  args = ["-m", "black", resolved];
} else {
  cmd = "npx";
  args = ["prettier", "--write", resolved];
}

const { stdout, stderr } = await execFileAsync(cmd, args, {
  cwd: WORKSPACE_ROOT,
  timeout: 30_000,
  maxBuffer: 512 * 1024,
  env: safeEnv(),
});

code_lint

Lint code using language-specific linters.

filePath

string

required

Path to source file

linter

string

Explicit linter: "eslint", "pylint", "clippy" (auto-detected by extension)

path

string

Linted file path

output

string

Linter output (JSON format if available)

exitCode

number

Exit code (0 = no issues, >0 = issues found)

Example:

const result = await trigger("tool::code_lint", {
  filePath: "src/api.ts"
});

// => {
//   path: "/workspace/src/api.ts",
//   output: '[{"ruleId":"no-unused-vars","severity":2,"message":"..."}]',
//   exitCode: 1
// }

Linter Selection:

Extension	Linter	Command
`.ts`, `.js`	ESLint	`npx eslint --format=json {file}`
`.py`	Pylint	`python3 -m pylint --output-format=json {file}`
`.rs`	Clippy	`cargo clippy --message-format=json`

Parsing Linter Output:

const result = await trigger("tool::code_lint", {
  filePath: "src/api.ts"
});

if (result.exitCode === 0) {
  console.log("No linting issues!");
} else {
  const issues = JSON.parse(result.output);
  for (const issue of issues) {
    console.log(`${issue.ruleId}: ${issue.message}`);
  }
}

code_test

Run tests using a specified test command.

command

string[]

required

Test command as array (e.g., ["npm", "test"])

cwd

string

Working directory for test execution

timeout

number

Timeout in milliseconds (default: 120,000 = 2 minutes)

stdout

string

Test output (stdout)

stderr

string

Test errors (stderr)

exitCode

number

Exit code (0 = all tests passed)

Example:

const result = await trigger("tool::code_test", {
  command: ["npm", "test"],
  cwd: ".",
  timeout: 60000
});

if (result.exitCode === 0) {
  console.log("All tests passed!");
  console.log(result.stdout);
} else {
  console.error("Tests failed:");
  console.error(result.stderr);
}

Supported Test Runners:

Language	Test Runner	Command Example
TypeScript/JavaScript	Vitest	`["npx", "vitest", "--run"]`
TypeScript/JavaScript	Jest	`["npm", "test"]`
Python	pytest	`["python3", "-m", "pytest"]`
Rust	cargo test	`["cargo", "test"]`
Go	go test	`["go", "test", "./..."]`

Allowed Test Commands:

// src/tools-extended.ts:995-1006
const ALLOWED_TEST_COMMANDS = new Set([
  "npm", "npx", "bun", "deno", "node",
  "python3", "python",
  "cargo", "go", "make"
]);

const binary = path.basename(command[0]);
if (!ALLOWED_TEST_COMMANDS.has(binary)) {
  throw new Error(
    `Test command not allowed: ${command[0]}. Allowed: ${[...ALLOWED_TEST_COMMANDS].join(", ")}`
  );
}

code_explain

Explain code using LLM analysis.

filePath

string

required

Path to source file

question

string

Specific question about the code (optional)

path

string

Analyzed file path

explanation

string

LLM-generated explanation

Example:

const result = await trigger("tool::code_explain", {
  filePath: "src/security-map.ts",
  question: "How does the HMAC verification prevent timing attacks?"
});

console.log(result.explanation);
// => "The code uses timingSafeEqual() for HMAC comparison, which ensures
//     constant-time execution regardless of input values. This prevents
//     attackers from using timing analysis to deduce the correct HMAC..."

Implementation:

// src/tools-extended.ts:1044-1067
const content = await readFile(resolved, "utf-8");
const truncated = content.slice(0, 50_000);  // Limit to 50KB

const prompt = question
  ? `Explain this code, focusing on: ${question}\n\n\`\`\`\n${truncated}\n\`\`\``
  : `Explain what this code does:\n\n\`\`\`\n${truncated}\n\`\`\``;

const result = await trigger("agent::chat", {
  agentId: "default",
  message: prompt
});

return { path: resolved, explanation: result.content };

Best Use Cases:

Understanding unfamiliar codebases
Documenting complex algorithms
Onboarding new developers
Security code reviews

Multi-Language Support

TypeScript/JavaScript

// Format with Prettier
await trigger("tool::code_format", { filePath: "src/index.ts" });

// Lint with ESLint
const lint = await trigger("tool::code_lint", { filePath: "src/index.ts" });

// Run tests with Vitest
const test = await trigger("tool::code_test", {
  command: ["npx", "vitest", "--run"]
});

Python

// Format with Black
await trigger("tool::code_format", { filePath: "main.py" });

// Lint with Pylint
const lint = await trigger("tool::code_lint", { filePath: "main.py" });

// Run tests with pytest
const test = await trigger("tool::code_test", {
  command: ["python3", "-m", "pytest", "tests/"]
});

Rust

// Format with rustfmt
await trigger("tool::code_format", { filePath: "src/main.rs" });

// Lint with Clippy
const lint = await trigger("tool::code_lint", { filePath: "src/main.rs" });

// Run tests with cargo
const test = await trigger("tool::code_test", {
  command: ["cargo", "test", "--", "--nocapture"]
});

Best Practices

Always format before committing

Run formatter before git commits to maintain code style:

// Pre-commit hook
const files = ["src/index.ts", "src/utils.ts"];
for (const file of files) {
  await trigger("tool::code_format", { filePath: file });
}

Use code_analyze for complexity tracking

Track code metrics over time:

const metrics = await trigger("tool::code_analyze", {
  filePath: "src/agent-core.ts"
});

if (metrics.functions > 50) {
  console.warn("Consider splitting this file into modules");
}

const complexity = metrics.codeLines / metrics.functions;
console.log(`Average function size: ${complexity} lines`);

Parse linter output for automation

Automate linter result processing:

const lint = await trigger("tool::code_lint", {
  filePath: "src/api.ts"
});

if (lint.exitCode !== 0) {
  const issues = JSON.parse(lint.output);
  const errors = issues.filter(i => i.severity === 2);
  
  if (errors.length > 0) {
    throw new Error(`${errors.length} linting errors must be fixed`);
  }
}

Set appropriate test timeouts

Adjust timeouts based on test suite size:

// Unit tests: 30s
await trigger("tool::code_test", {
  command: ["npm", "test", "--", "unit"],
  timeout: 30000
});

// Integration tests: 5min
await trigger("tool::code_test", {
  command: ["npm", "test", "--", "integration"],
  timeout: 300000
});

Common Patterns

CI/CD Pipeline

// Format, lint, test pipeline
const file = "src/tools.ts";

// 1. Format
console.log("Formatting...");
await trigger("tool::code_format", { filePath: file });

// 2. Lint
console.log("Linting...");
const lint = await trigger("tool::code_lint", { filePath: file });
if (lint.exitCode !== 0) {
  console.error("Linting failed:", lint.output);
  process.exit(1);
}

// 3. Test
console.log("Testing...");
const test = await trigger("tool::code_test", {
  command: ["npm", "test"]
});
if (test.exitCode !== 0) {
  console.error("Tests failed:", test.stderr);
  process.exit(1);
}

console.log("✅ All checks passed!");

Code Review Assistant

// Analyze code before review
const metrics = await trigger("tool::code_analyze", {
  filePath: "src/new-feature.ts"
});

const explanation = await trigger("tool::code_explain", {
  filePath: "src/new-feature.ts",
  question: "What are the potential security concerns?"
});

const report = {
  metrics,
  complexity: (metrics.codeLines / metrics.functions).toFixed(1),
  securityReview: explanation.explanation
};

console.log(JSON.stringify(report, null, 2));

Refactoring Workflow

// Before refactoring
const before = await trigger("tool::code_analyze", {
  filePath: "src/legacy.ts"
});

// Perform refactoring (manual or automated)
// ...

// After refactoring
const after = await trigger("tool::code_analyze", {
  filePath: "src/legacy.ts"
});

console.log(`Functions: ${before.functions} → ${after.functions}`);
console.log(`Code lines: ${before.codeLines} → ${after.codeLines}`);
console.log(`Complexity reduced: ${(
  (before.codeLines / before.functions) -
  (after.codeLines / after.functions)
).toFixed(1)} lines/function`);

Error Handling

try {
  await trigger("tool::code_format", { filePath: "src/syntax-error.ts" });
} catch (err) {
  console.error("Formatting failed:", err.message);
  // Handle syntax errors gracefully
}

try {
  const result = await trigger("tool::code_test", {
    command: ["invalid-command"]
  });
} catch (err) {
  console.error(err.message);
  // "Test command not allowed: invalid-command. Allowed: npm, npx, ..."
}

File Operations — Read and write source files
Shell Execution — Run build commands
Git Tools — Version control integration

Get Started

Core Concepts

CLI Reference

Tools & Capabilities

Control Plane

Security

Advanced Features

Templates & Examples

Available Tools

code_analyze

code_format

code_lint

code_test

code_explain

Multi-Language Support

TypeScript/JavaScript

Python

Rust

Best Practices

Common Patterns

CI/CD Pipeline

Code Review Assistant

Refactoring Workflow

Error Handling

Build docs developers (and LLMs) love

Get Started

Core Concepts

CLI Reference

Tools & Capabilities

Control Plane

Security

Advanced Features

Templates & Examples

​Available Tools

​code_analyze

​code_format

​code_lint

​code_test

​code_explain

​Multi-Language Support

​TypeScript/JavaScript

​Python

​Rust

​Best Practices

​Common Patterns

​CI/CD Pipeline

​Code Review Assistant

​Refactoring Workflow

​Error Handling

​Related Tools

Build docs developers (and LLMs) love

Available Tools

code_analyze

code_format

code_lint

code_test

code_explain

Multi-Language Support

TypeScript/JavaScript

Python

Rust

Best Practices

Common Patterns

CI/CD Pipeline

Code Review Assistant

Refactoring Workflow

Error Handling

Related Tools