codeact.instructions.md.tmpl

---
applyTo: "**"
---

## CodeAct — sandboxed Python (backend: {{BACKEND}})

Use codeact **instead of** chained tool calls when a task reads ≥8 files,
cross-references file sets, or needs ≥5 sequential tool calls.

### Invoke

```bash
{{CODEACT_DIR}}/scripts/codeact --auto --raw --workspace . --code '<python>'
```

### Critical rules

1. **One bash call, one program.** Write a single Python program that globs,
   reads, analyzes, and prints results. Do NOT scout with view/glob before
   invoking codeact. Do NOT retry with extra tool calls if the first run
   has a minor issue — fix the program instead.
2. **Return types** — getting these wrong causes retries:
   - `glob` → **list of strings** like `["src/app.py", ...]`
   - `view` → **string** (file content)
   - `mcp_call` → **string**
   - `bash` → **dict** with stdout/stderr/returncode
3. **No `os.path`, no `os.walk`** — use `glob` to find files, `view` to read them.
4. **`glob` auto-excludes** `.venv`, `node_modules`, `__pycache__`, `.git`, `target`,
   `dist`, `build`, and similar directories. If you need files from those dirs,
   pass `exclude_dirs=[]` to disable filtering.
5. **Wrap file reads in try/except.** Print partial results as you go.
6. **Use double quotes in Python code** to avoid shell quoting conflicts with
   `--code '...'`. Write `"string"` not `'string'` inside codeact programs.
7. Skip codeact for ≤5 files or single grep→view→done workflows.
8. **Keep output minimal.** Only print what the caller actually needs —
   summaries, counts, and key findings. Do NOT dump raw file contents or
   hundreds of unfiltered lines. If a list could be long, truncate or
   aggregate inside the program. The output must fit comfortably in a
   single tool response (~5 KB) to avoid extra read round-trips.

{{SYNTAX}}

{{BACKEND_LIMITATIONS}}

### Sandbox tools: {{TOOL_LIST}}

{{TOOL_REFERENCE}}