> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wrenn.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Stateful Code Execution with Wrenn Code Interpreter

> The Wrenn code interpreter runs Python code in a persistent Jupyter kernel inside a capsule, preserving state across multiple run_code calls.

The code interpreter is a specialized capsule that embeds a persistent Jupyter kernel. Unlike running a Python script with `capsule.commands.run()`, the interpreter keeps the kernel alive between calls — variables, imports, and function definitions all survive from one `run_code()` call to the next.

## Quick start

```python theme={null}
from wrenn.code_interpreter import Capsule

with Capsule(wait=True) as capsule:
    result = capsule.run_code("print('hello')")
    print("".join(result.logs.stdout))  # "hello\n"
```

The `Capsule` class in `wrenn.code_interpreter` extends the standard capsule with `run_code()`. Pass `wait=True` to block until the capsule is running before you execute any code.

## Stateful execution

The kernel persists between calls, so every assignment, import, and function definition you make in one call is available in the next.

```python theme={null}
from wrenn.code_interpreter import Capsule

with Capsule(wait=True) as capsule:
    # Assign a variable
    capsule.run_code("x = 42")
    result = capsule.run_code("x * 2")
    print(result.text)  # "84"

    # Import a module
    capsule.run_code("import math")
    result = capsule.run_code("math.pi")
    print(result.text)  # "3.141592653589793"

    # Define a function
    capsule.run_code("def greet(name): return f'hello {name}'")
    result = capsule.run_code("greet('world')")
    print(result.text)  # "hello world"
```

## Reading output

`run_code()` returns an `Execution` object. Use `result.text` for the value of the last expression in a cell, and `result.logs.stdout` / `result.logs.stderr` for printed output.

```python theme={null}
with Capsule(wait=True) as capsule:
    # Expression value — available on result.text
    result = capsule.run_code("1 + 1")
    print(result.text)  # "2"

    # Print output — available in result.logs.stdout
    result = capsule.run_code("print('from print')")
    print("".join(result.logs.stdout))  # "from print\n"

    # stderr
    result = capsule.run_code("import sys; sys.stderr.write('warn\n')")
    print("".join(result.logs.stderr))  # "warn\n"
```

`result.text` returns the `text/plain` representation of the main `execute_result` — the last expression in the cell. Calls to `print()` go to `result.logs.stdout`, not `result.text`.

## Templates

The code interpreter uses the `code-runner-beta` template by default. Pass a `template=` argument to use a custom Jupyter-enabled template instead.

```python theme={null}
capsule = Capsule(template="my-custom-jupyter-template", wait=True)
result = capsule.run_code("print('running on custom template')")
```

<Tip>
  The code interpreter capsule inherits all standard capsule features. You can use `capsule.commands`, `capsule.files`, `capsule.git`, and everything else alongside `run_code()`.

  ```python theme={null}
  with Capsule(wait=True) as capsule:
      capsule.run_code("import pandas as pd; df = pd.DataFrame({'a': [1,2,3]})")
      capsule.run_code("df.to_csv('/tmp/data.csv', index=False)")

      # Read the file back with the standard files API
      content = capsule.files.read("/tmp/data.csv")
      print(content)
  ```
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Execution" icon="play" href="/code-interpreter/execution">
    Learn about the `Execution` object, error handling, and streaming callbacks.
  </Card>

  <Card title="Rich output" icon="image" href="/code-interpreter/rich-output">
    Capture charts, images, HTML, and other rich MIME outputs from your code.
  </Card>
</CardGroup>