# EONYX recipes: practical workflows


Features are nice.
Seeing them work is better.
A few practical scenarios: how to phrase the task, and which technique to switch on.
The prompts are deliberately plain.

<!--more-->

## 💻 Working with code

### Understand unfamiliar code

Start in plan mode, so the agent explores before it 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
```

Plan mode allows reading only.
The agent walks the code with `grep`, `read` and `glob`, then proposes a plan or a summary.
Heavy exploration is worth delegating, 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" >}}
Add an `AGENTS.md` with the stack and the rules.
The agent picks them up from the first message.
That is a lot less to explain every time.
{{< /admonition >}}

### Fix a failing test

Let the agent run commands and edit files.
Headless with `--yolo` is the shortest path:

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

Or do it in the TUI: allow the tools you need, then ask.
Showing the output first helps:

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

A command run through `!` 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 step by step:

```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 it goes sideways, return to the original session from the list with `Ctrl+S`.
Attach formatting as a hook and stop asking for it:

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

## 🔁 Automating routine work

### Prepare a release

Put the checklist into a skill once:

```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.
Back the no-push rule with a guardrail hook on `bash`, because that is how the agent runs `git push`.
The `git_commit` tool only commits.

### A one-off task in a script

EONYX drops into a pipe easily.
The result goes to stdout, everything else 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, reach for `--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 >}}