# EONYX recipes: practical workflows


Features are nice, but it is more interesting to see them at work. A few practical scenarios: how to phrase the task and which EONYX techniques to turn on. The prompts are deliberately plain.

<!--more-->

## Working with code

Three common tasks in interactive mode: understand someone else's code, fix a test and carefully rewrite a module.

### Understand unfamiliar code

Start with a plan so the agent explores first instead of jumping into edits:

```text
/plan
figure out how authorization works in this repository,
and put together a short map: where the entry point is, where sessions are stored
```

In plan mode only reading is available, so the agent walks over the code safely (`grep`, `read`, `glob`) and proposes a plan or a summary. Heavy exploration can be delegated to a subagent so it does not clutter the context:

```text
via task: find every place where the Store interface is called and return a list
```

{{< admonition type="tip" title="Keep an AGENTS.md" >}}
If you add an `AGENTS.md` with the project stack and rules, the agent will take them into account from the very first message — less to explain every time.
{{< /admonition >}}

### Fix a failing test

Let the agent run commands and make edits — the simplest way is headless with `--yolo`:

```bash
eonyx run --yolo "run go test ./... , find the cause of the failure and fix it without touching the public API"
```

Or in the TUI: allow the tools you need and ask. It helps to show the output first:

```text
! go test ./...
fix the failure above with a minimal change
```

A command run via `!` is recorded into the conversation, so the model sees the real test output.

### Refactor a module

Fork the session as a save point, then drive the edits iteratively:

```text
/fork
move config parsing out of main.go into a separate config package,
preserve the behavior, update the imports and run go build ./...
```

If something goes wrong, you can return to the original session from the list (`Ctrl+S`). Auto-formatting can be attached as a hook so you do not have to ask every time:

```json
"hooks": { "edit": { "after": "gofmt -w ." }, "write": { "after": "gofmt -w ." } }
```

## Automating routine work

Repeated operations are worth setting up once — as a skill, a hook or a pipe in a script.

### Prepare a release

Collect the checklist as a skill so you do not have to repeat it:

```markdown
---
name: release
description: Release checklist. Use when asked to prepare a release, ship it, or cut a tag.
---
1. git_status — the tree is clean, the branch is main.
2. go test ./... and go vet ./... — green.
3. Propose the next tag from git describe --tags; do NOT push without confirmation.
```

After that "prepare a release" is enough — the agent loads the skill and follows the steps. The ban on pushing without confirmation can be duplicated with a guardrail hook on the `bash` tool — that is how the agent invokes `git push` (the `git_commit` tool only commits).

### A one-off task in a script

EONYX is easy to embed in a pipe: the result goes to stdout, everything auxiliary to stderr.

```bash
# generate a draft README from the code
eonyx run "write a README for this repository, short and to the point" > README.draft.md

# explain an error from the log (the argument takes priority over stdin,
# so the prompt and the log are fed to stdin as a single stream)
{ echo "explain the cause of the error and suggest a fix:"; cat error.log; } | eonyx run
```

For machine parsing — `--json` and `jq`:

```bash
eonyx run --yolo --json "run the linter and fix the warnings" | jq -r 'select(.type=="result").text'
```

## Summary

{{< admonition type="abstract" title="Cheat sheet" >}}
- **Exploration**
  - `/plan` — read-only, a safe walk over the code
  - delegate via `task`, keep an `AGENTS.md`
- **Fixing**
  - `--yolo` in headless mode or a `!` command in the TUI
  - the model sees the real test output
- **Refactoring**
  - `/fork` as a save point
  - auto-formatting via an `after` hook
- **Release**
  - put the checklist into a skill
  - the ban on pushing — a hook on `bash`
- **Scripts**
  - stdout = result, stderr = auxiliary output
  - `--json` + `jq` for machine parsing
{{< /admonition >}}