> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# CodeAgent
> Agent that generates, executes, reviews and refactors code with a pluggable executor
`CodeAgent` generates, executes, reviews, and refactors code, and only runs code when you name an explicit executor.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
A[📝 Input] --> B[🤖 CodeAgent]
B --> C[generate]
B --> D[execute]
B --> E[review]
B --> F[refactor]
C --> G[✅ Output]
D --> G
E --> G
F --> G
classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
classDef action fill:#189AB4,stroke:#7C90A0,color:#fff
classDef output fill:#10B981,stroke:#7C90A0,color:#fff
class A input
class B agent
class C,D,E,F action
class G output
```
## Quick Start
```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { CodeAgent, createSubprocessExecutor } from 'praisonai';
const agent = new CodeAgent({
name: 'Coder',
code: {
executor: createSubprocessExecutor(), // opt-in real runner
allowedLanguages: ['python'],
timeout: 20,
},
});
const result = await agent.execute('print(2 + 2)', 'python');
console.log(result.output); // "4\n"
console.log(result.success); // true
```
```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
const code = await agent.generate('Write a function to reverse a string');
const review = await agent.review(code);
const better = await agent.refactor(code, 'add type hints');
```
***
## Why an explicit executor?
Execution is granted by naming a runner, never by flipping a boolean.
Without `code.executor`, `execute()` returns `{ success: false, error: 'No code executor is configured...' }`. This is deliberate, so model-generated code cannot silently run in-process.
```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
const agent = new CodeAgent({ name: 'Coder' }); // no executor
const result = await agent.execute('print(2 + 2)', 'python');
console.log(result.success); // false
console.log(result.error); // "No code executor is configured, so 'python' code was not run. ..."
```
***
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant CodeAgent
participant Executor
participant Runner
User->>CodeAgent: execute(code, language)
CodeAgent->>CodeAgent: check allowedLanguages
CodeAgent->>Executor: run(code, language, context)
Executor->>Runner: child process (cwd, env, timeout)
Runner-->>Executor: stdout / stderr / exit code
Executor-->>CodeAgent: CodeExecutionResult
CodeAgent-->>User: { success, output, error }
```
***
## CodeConfig
| Field | Type | Default | Purpose |
| ------------------ | ------------------------ | --------------- | ---------------------------------------------------------------------- |
| `executor` | `CodeExecutor` | — | The only way to make `execute()` actually run code. |
| `sandbox` | `boolean` | `true` | Advisory hint passed through to the executor. Does NOT gate execution. |
| `timeout` | `number` (seconds) | `30` | Kills the whole process tree on timeout (SIGKILL). |
| `allowedLanguages` | `string[]` | `['python']` | Gate at the CodeAgent level. |
| `maxOutputLength` | `number` | `10000` | Output capped as chunks arrive (bounded memory). |
| `workingDirectory` | `string` | `process.cwd()` | Passed to the executor. |
| `environment` | `Record` | `{}` | Merged with `process.env`. |
***
## createSubprocessExecutor()
`createSubprocessExecutor()` is a ready-made out-of-process runner.
```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { CodeAgent, createSubprocessExecutor } from 'praisonai';
const agent = new CodeAgent({
code: { executor: createSubprocessExecutor() },
});
```
Default interpreter map:
| Language | Interpreter |
| -------------------- | ----------------------------------------------------- |
| `python`, `python3` | `process.env.PRAISONAI_PYTHON ?? 'python3'` with `-c` |
| `javascript`, `node` | `process.execPath` with `-e` |
| `bash` | `bash -c` |
| `sh` | `sh -c` |
* Runs a detached child on non-Windows so the timeout kills the whole process group.
* Truncates output live during streaming, not after close.
* An unregistered language returns `{ success: false, error: "No interpreter is registered for ''. Known: ..." }`.
Set **`PRAISONAI_PYTHON`** to override the interpreter used for `python` / `python3`.
***
## Writing your own executor
Supply a `CodeExecutor` to target a container, microVM, e2b, or a remote sandbox service.
```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { CodeAgent, type CodeExecutor, type CodeExecutorContext } from 'praisonai';
const remoteExecutor: CodeExecutor = async (code, language, context: CodeExecutorContext) => {
// Send code to your container / microVM / remote sandbox
return {
success: true,
output: '...',
exitCode: 0,
executionTime: 0.1,
};
};
const agent = new CodeAgent({ code: { executor: remoteExecutor } });
```
The `CodeExecutor` signature:
```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
type CodeExecutor = (
code: string,
language: string,
context: CodeExecutorContext,
) => Promise;
```
`CodeExecutorContext` carries `sandbox`, `timeout`, `workingDirectory`, `environment`, and `maxOutputLength`.
A child process is **not** a security sandbox — it shares the host filesystem, network and user. For untrusted code, supply your own executor targeting a container, microVM, or remote sandbox service.
***
## Best Practices
Never rely on a boolean to enable execution. Pass `createSubprocessExecutor()` or your own runner so execution is a visible decision.
Set `allowedLanguages` to only the languages you expect. `execute()` rejects any other language before the executor runs.
Supply a container or microVM executor for model-generated or user-supplied code. The subprocess runner shares the host.
Keep `maxOutputLength` and `timeout` sensible. Output is capped as it streams and the timeout kills the whole process tree.
***
## Related
The generic Agent `executeCode()` sandbox (separate API)
Agent configuration and capabilities
Where agents run