Ene Documentation

Getting Started

Install

Ene requires Python 3.10 or newer.

pip install ene-agent
bash

Confirm that the CLI is available:

ene --help
bash

Configure a model

Ene reads model and global settings from ~/.ene.yaml:

OpenAI-compatible APIs

Add one entry under openai for each model alias. Use the model ID, API key, and base URL supplied by your service:

openai:
  fast:
    model: deepseek-v4-flash
    api_key: replace-with-your-api-key
    base_url: https://api.deepseek.com

  my_model:
    model: provider-model
    api_key: replace-with-your-api-key
    base_url: https://provider.example/v1
    reasoning_effort: high # optional; defaults to high
yaml

The alias (fast or my_model above) is what you pass to --model. Startup --model, the interactive /model command, and Python's run_agent(model_alias=...) also accept a unique prefix of a configured alias. For example, gpt-6 selects gpt-6-astra when that is the only matching alias. An exact alias always wins; an ambiguous prefix produces an error listing its matches. Matching is case-sensitive.

API-key models use Chat Completions by default. Set api: responses on an individual model to use an OpenAI-compatible Responses endpoint instead:

openai:
  gpt-6:
    provider: openai
    api: responses # optional; defaults to chat_completions
    model: azure/openai/gpt-6-astra
    api_key: replace-with-your-api-key
    base_url: https://inference-api.nvidia.com
    reasoning_effort: high
yaml

Use the model ID and base URL supplied by your service. Ene appends /responses to the base URL; for OpenAI's public API use https://api.openai.com/v1 and model: gpt-6-astra. The only supported api values are chat_completions and responses. The setting also applies to /model switches, the Python API, batch jobs, and models selected for recap or compaction.

Responses mode supports streaming, images, function calls, and structured JSON output. Ene uses store: false and carries returned output items, including encrypted reasoning when the service supplies it, in local conversation and session history. Gateway support for individual features can vary. The openai-codex subscription provider always uses Responses independently of this API-key setting.

ChatGPT Plus/Pro subscription

The openai-codex provider authenticates through a ChatGPT subscription instead of an API key:

openai:
  codex:
    provider: openai-codex
    model: gpt-5.6-sol
    reasoning_effort: high # optional

  gpt-6-astra:
    provider: openai-codex
    model: gpt-6-astra
    reasoning_effort: high # optional
yaml

Start Ene and authenticate from the chat prompt:

ene --model codex

# in the chat prompt, run
/login openai-codex
bash

Choose one of the offered browser, manual-redirect, or device-code flows. OAuth credentials are stored in ~/.ene/auth.json. Use /auth to check login status and /logout to remove the credentials.

List configured models

List resolved aliases, providers, APIs, context windows, and reasoning settings:

ene models
bash

When --model is omitted, the first configured entry is used.

Subagents launched through exec_command or start_process inherit the session's model and reasoning effort automatically (via ENE_MODEL_ALIAS and ENE_REASONING_EFFORT in the child environment), so a delegated agent runs with the same configuration as the parent unless explicitly overridden.

CLI

Run Ene in the current directory:

ene
bash

Useful commands during a session include:

Command Purpose
/help Show interactive commands.
/context [user|assistant|id] List context messages, filter by role, or inspect one in full (-1 is the newest).
/usage Show token usage.
/recap Summarize the current task in one sentence.
/export <path/filename> Export the last assistant response to a file.
/model Show or switch the active model.
/persona List or switch personas.
/skills List reusable skills.
/rewind Return conversation or code to an earlier prompt.
/fork [name] Start a new session from an earlier prompt boundary.
/exit Save and exit.

Prefix a shell command with ! to run it directly without asking the model:

!git status
!pytest -q
text

Tool calls execute automatically. Ene has the same permissions as the shell user and is not a security boundary. Use an OS-level sandbox or container when commands must be constrained.

See CLI and Tools for the complete interfaces.

Python API

Use run_agent() for a single non-interactive task with the configured model:

from ene import run_agent

result = run_agent("Review the changes in this project", work_dir=".")
if result.success:
    print(result.response)
else:
    print(result.outcome, result.error)
python

Responses that truncate during a tool call, are stopped by a provider content filter, or remain unfinished after automatic continuations return TurnOutcome.FAILED, with success=False and an explanatory error. Content-filtered responses stop without executing tool calls or automatically continuing. Any final partial text is retained in response.

Persistent live sessions

Interactive sessions run in detached workers and survive closing the terminal or shell. While attached, the terminal tab shows ◐ ene [name] / ◑ ene [name] while Ene is working and ✓ ene [name] when it is ready; unnamed sessions use the workspace directory name. Terminal profiles configured to suppress application titles will ignore these updates.

  • Start with an optional name using ene [name] (equivalent to ene new [name]).
  • Detach without interruption using /detach or Ctrl+D.
  • Rename the session with /name [name].
  • List workers with ene ls (ene l).
  • Reattach with ene attach [name], or choose with bare ene attach (ene a).
  • Switch sessions using /switch or Ctrl+S; cancelling the picker leaves the current attachment untouched.
  • Terminate the attached session with Ctrl+K, or use the ene kill (ene k) multi-select picker.
  • Use /resume to activate a stopped conversation in the current live worker.

Resume, attach, and switch replay the latest 10 user turns and final assistant responses, omitting historical tool activity and warnings. Ctrl+K, double Ctrl+C at an idle prompt, and explicit exit/quit terminate the live session. Workers are not restarted after a machine reboot. Closing a terminal never stops the session: work continues in the detached worker even when the shell is closed mid-task, and a force-closed terminal (for example a killed shell) frees the attachment automatically after about 20 seconds of silence. Reattaching inside that window waits for the release instead of failing, so ene attach right after a force-close simply pauses for a moment and then connects.

Resume a session

Sessions and other project-local Ene state are stored under ./.ene/. Ene maintains ./.ene/.gitignore with *, so this state is not committed accidentally.

Choose a previous session interactively:

ene resume
bash

Or resume a known session directly:

ene resume SESSION_ID
bash

Within a running session, /rewind previews an earlier prompt boundary and lets you restore the conversation, tracked file changes, or both. The selected prompt returns to the editor so you can revise it before branching. /fork [name] uses the same prompt picker but starts a new, optionally named session at that conversation state, leaving both the old session and tracked files unchanged.

When write_file, edit_file, or multi_edit writes through a symlink, rewind restores the target file and preserves the symlink. This also applies to targets outside the workspace and paths reached through a symlinked directory.

Type to search.