Metadata-Version: 2.5
Name: euron-code
Version: 0.6.0
Summary: Euron Code: an agentic coding assistant in your terminal for Euron Plus and Super 30 students.
Project-URL: Homepage, https://euron.one/code-agent
Author-email: Euron <contact@euron.one>
License: Copyright (c) 2026 Euron. All rights reserved.
        
        This software and its source code, documentation and associated files (the
        "Software") are proprietary to Euron and are protected by copyright law.
        
        Euron grants you a limited, non-exclusive, non-transferable, revocable licence
        to install and run the Software solely to access the Euron Code service with an
        Euron account that is entitled to it (for example Euron Plus or Super 30).
        
        You may not, without the prior written permission of Euron:
          - copy, modify, merge, publish, distribute, sublicense or sell the Software
            or any part of it;
          - reverse engineer, decompile or disassemble the Software, except to the
            extent that applicable law expressly permits it;
          - use the Software to access any service other than Euron Code, or to
            circumvent any access control, quota or rate limit of the service.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
        FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL EURON BE LIABLE
        FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
        TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
        THE USE OR OTHER DEALINGS IN THE SOFTWARE.
License-File: LICENSE
Keywords: ai,assistant,cli,coding agent,euron
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Requires-Python: >=3.9
Requires-Dist: httpx<1,>=0.24
Requires-Dist: keyring>=23.0
Requires-Dist: prompt-toolkit>=3.0.30
Requires-Dist: pypdf>=3.0
Requires-Dist: rich>=13.0
Provides-Extra: browser
Requires-Dist: playwright>=1.40; extra == 'browser'
Provides-Extra: db
Requires-Dist: psycopg[binary]>=3.1; extra == 'db'
Requires-Dist: pymysql>=1.0; extra == 'db'
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Provides-Extra: images
Requires-Dist: pillow>=9.0; extra == 'images'
Provides-Extra: mysql
Requires-Dist: pymysql>=1.0; extra == 'mysql'
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
Description-Content-Type: text/markdown

# Euron Code

**Imagine It. Prompt It. Build Anything.**

Your AI Software Engineer. Ready to Build.

From a simple website to a complete AI-powered application, Euron Code turns your ideas into real,
working software.

It doesn't just write code. It thinks, plans, builds, runs, tests, finds errors, and fixes them. All from
your terminal.

No more starting from scratch. Euron Code intelligently reuses existing open-source implementations,
writes what's missing, and brings everything together.

One idea. One prompt. Endless possibilities.

## Get started in 3 steps

**1. Install** (Python 3.9 or newer; Windows, macOS, Linux). From PyPI, https://pypi.org/project/euron-code/:

```bash
pip install euron-code
```

**2. Run it in your project folder:**

```bash
cd my-project
euron
```

The first time, your browser opens to log in with your Euron account (one click to approve; the key is
then saved on your computer). In a new folder, Euron Code offers to set the project up for you: press
Enter.

**3. Type what you want**, or type `/` to see every command:

- `build me a todo app with a FastAPI backend and tests`
- `the tests fail, find out why and fix them`
- `/usage` to see your tokens today, this week, month and year

That's it. Press **Esc** to stop it, **Ctrl-D** to quit.

## Everything you need to build

- 🧠 **Thinks Before It Codes**: understands your requirements and plans the implementation.
- ⚡ **Builds Complete Applications**: websites, SaaS products, AI agents, APIs, dashboards, automations,
  and more.
- 🛠️ **Writes, Runs & Fixes**: creates files, executes commands, runs tests, and fixes errors.
- 🔍 **Reuses Proven Code**: discovers reusable Euron and approved open-source components to build faster.
- 🔄 **Works Across Your Project**: understands existing code and makes changes without unnecessarily
  rebuilding everything.
- 🚀 **From Idea to Working Software**: helps you build, test, and prepare real applications for
  deployment.

## 10 million AI tokens every day

Build more. Experiment more. Create without constantly worrying about tokens.

*Up to 10 million tokens per day, subject to fair-use policies, model availability, and plan limits.*

Included with **Euron Plus** and **Super 30** (get Plus at https://euron.one/plus).

Track your usage any time: `euron usage` in a terminal, `/usage` in a session, or
https://euron.one/code-agent/usage.

*Euron Code: You Imagine. We Code. You Create.*

## What happens automatically

- **Project setup.** The first time in a folder it writes `EURON.md` (your stack, build and test
  commands, layout), rules for your stack, handy commands (`/fix-tests`, `/commit`, `/pr`) and safe
  permission settings. Locally, in a second, no AI call. Edit the files freely; `/init` lets the AI
  improve `EURON.md`.
- **Context management.** Old tool output is cleared and long conversations are summarised before
  they fill the context, so it never runs out mid-task. Long answers continue by themselves.
- **Token saving.** Unchanged files are not re-read and big files are read in parts.
- **Local cache.** `.euron/cache/` remembers the repo map and file list, so new sessions start fast.
  Safe to delete; never holds secrets; git-ignored.
- **Runs your app.** It can start your dev server in the background, check it answers
  (`check_app`, optionally in a headless browser), read its logs and stop it again.
- **Builds from references, not from scratch.** For "build me X" and for UI work it first searches
  Euron's open-source repos, then permissively licensed projects on GitHub, reads only the files it needs,
  adapts them (keeping the licence notice and recording each source in `THIRD_PARTY_NOTICES.md`) and
  writes only what is missing. Faster, and far fewer tokens. Try `/reference <what you want to build>`.
- **Live progress.** While it works you see what it is doing, the time, tokens and an `esc to interrupt`
  line, and you can keep typing (see below).

## Commands

Type `/` and pick from the menu. The most useful:

| Command | What it does |
|---|---|
| `/model` | pick a model with the arrow keys (works while a task runs) |
| `/usage` | your quota today, this week, month and year, refill times, and what it is worth |
| `/status` | account, key, model, mode, session time and quota at a glance |
| `/cost`, `/context` | tokens of this session and what fills the context |
| `/attach <files>` | attach files, folders, Word/Excel/PowerPoint/PDF documents or images |
| `/reference <what>` | references to build from: Euron's repos + permissive open source, with licences |
| `/reuse <query>` | search Euron's open-source repos for code to reuse |
| `/components` | your component library: reused code whose tests passed in your projects |
| `/ps` | background processes (dev servers) it started; `/ps stop` |
| `/plan` | plan mode: it explores and proposes a plan, changes nothing |
| `/review` | review your uncommitted changes |
| `/rewind` (or Esc Esc) | undo the last turn's file changes |
| `/compact`, `/clear` | summarise the conversation, or start fresh |
| `/resume`, `/export` | go back to a saved session, or save this one as Markdown |
| `/effort low\|medium\|high` | how much the model thinks before answering |
| `/login`, `/logout`, `/whoami` | switch account, log out, who am I |
| `/help` | everything else: rules, skills, hooks, memory, permissions, config, bug, release notes |

Shortcuts: `@file` attaches a file (Tab completes), drag files or screenshots into the terminal to attach
them, `!command` runs a shell command yourself, `# note` saves a note to memory, **Shift+Tab** changes
the mode, **Ctrl+V** pastes an image (with Pillow installed).

### Typing while it works

The task runs in the background and the prompt stays live. `/usage`, `/cost`, `/context`, `/status`,
`/model`, `/effort`, `/todos`, `/permissions` and `/help` answer at once (a model change applies from the
next step, a mode change from the next tool call). Anything else you type is queued as your next
message. **Esc** or **Ctrl-C** stops the task, including a running command, and puts queued messages
back in the input line. Permission questions are answered in the same prompt.

The bottom bar always shows the model and effort, the mode, this session's tokens and their value,
how full the context is, what is left today and this week, and how long the session has been up.

## Modes

| Mode | How | What it does |
|---|---|---|
| default | | asks before edits, commands and web fetches |
| acceptEdits ("auto-apply") | Shift+Tab, or `--permission-mode acceptEdits` | edits inside the project apply without asking; commands still ask |
| plan | Shift+Tab twice, `/plan` | read-only; it proposes a plan, you decide when it may act |
| bypass | `euron --dangerously-skip-permissions` (or `--permission-mode bypassPermissions`, `--yolo`) | nothing asks. Only in a throwaway folder or container. Paths outside the project still ask |

Shift+Tab cycles default -> acceptEdits -> plan, and reaches bypass only if you started with it.
`--add-dir ../shared` lets it also work in another folder.

## Your code and your account

- Your code stays on your computer.
- One login at a time: signing in on another computer signs this one out.
- Don't paste passwords or API keys into prompts.

## How Euron Code reuses proven code

Search first, reuse second, modify third, generate only what is missing. When you ask it to build an app,
a feature, a UI or an integration, Euron Code itself splits the request into a few components and asks
Euron for proven code for each one before the model starts (the model can ask for more with
`find_reusable`): Euron's own repositories, your own component library and approved open-source
projects. You see a decision table
(component, REUSE / ADAPT / GENERATE, repository@commit, licence, confidence). REUSE reads the pinned files
and integrates them with minimal edits, ADAPT reads and modifies them, GENERATE writes the part itself.
For websites and UI it asks for Euron's TypeScript / TSX components. Small edits, bug fixes and questions
skip this step. The details you give (your name, photo, email, links) go into the files; an attached
photo is copied into the project's `assets/` (or `public/`) folder, and if a changed file still says
"Your Name" or "Lorem ipsum" Euron Code is asked once to fix it. If that search is unavailable it simply generates,
with a short note. When the tests pass on reused or adapted code, the component is added to
your private library (its name, source, commit, licence and test result; never your code): `/components`
lists it. Turn reuse off with `--no-reuse` for one run, `reuse.enabled false`, or keep it to Euron's own
code with `reuse.external false`.

Licence rules: only MIT, Apache-2.0, BSD, ISC, 0BSD, Unlicense, MPL-2.0, CC0 and Zlib code is reused (see
below); a candidate whose licence or security scan fails is always turned into GENERATE by the CLI itself,
whatever the server says.

## Reusing open source safely

Only code under MIT, Apache-2.0, BSD-2/3-Clause, ISC, 0BSD, Unlicense, MPL-2.0, CC0-1.0 or Zlib is used.
GPL, AGPL, LGPL, SSPL and unlicensed code is never copied: Euron does not serve it and the CLI checks
again. MPL-2.0 files stay separate files under their own licence. Every reused source is recorded in
your project's `THIRD_PARTY_NOTICES.md`, and the completion report lists it (`Reused: owner/repo/path
(MIT)`).

### All of GitHub, from your own computer

Euron Code searches all public repositories on GitHub directly from your machine, so you get your own
GitHub allowance (and code search too when you are signed in with `gh auth login` or set `GITHUB_TOKEN`;
the token is only ever sent to GitHub, never to Euron, and never printed). A chosen reference is
downloaded once at a pinned commit into `~/.euron/cache/oss`, indexed on your computer, and reused in
later sessions: searching it and reading parts of it needs no network and no tokens. `oss_adopt` copies
the few files that are worth reusing into your project with their licence header, copies the LICENSE
(and NOTICE for Apache-2.0) to `third_party/licenses/`, and records repo, commit, licence and files in
`THIRD_PARTY_NOTICES.md`. The licence comes from GitHub's licence detection and is checked in code: a
repo with no detected licence, NOASSERTION, GPL, AGPL, LGPL, SSPL, BUSL, a non-commercial licence or a
Commons Clause rider is refused.

`euron cache` lists what is cached, `euron cache size` shows the total, `euron cache clear [owner/name]`
removes it. The cache keeps up to 2 GB (least recently used first out; `reuse.cacheMaxMB`) and at most
50 MB per repo (`reuse.repoMaxMB`). `reuse.local false` (or `EURON_OSS_LOCAL=0`) asks Euron's service
instead of GitHub; when GitHub is offline or its rate limit is reached, Euron Code falls back to it by
itself. Full walk-through: [docs/USE_CASES_REUSE.md](docs/USE_CASES_REUSE.md).

## Limits and value

Your plan has a token allowance per **day**, **week**, **month** and **year**, the same for Euron Plus
and Super 30.
`/usage` (or `euron usage`) shows each with a bar, what is left and when it refills, in your local time.
Days, weeks (Monday), months and years start at midnight IST. If a limit is reached, Euron Code says
which one and when it refills; nothing else breaks.

It also shows what your own usage would cost at reference market API prices. **It is not a bill: you
pay nothing extra.** The same numbers are on https://euron.one/code-agent/usage.

## Run and check your app

`start_background_process` starts a dev server or watcher and waits until its port answers (or a ready
line appears); `check_app` requests a local URL (`localhost` only) and reports the status, timing, title
and whether expected text is there; `read_process_output` shows its logs and `stop_process` stops it.
At most 3 run at once, and all of them are stopped when you exit, `/clear` or `/rewind`. With
`pip install "euron-code[browser]"` and `playwright install chromium`, `check_app` can also open the page
in a headless browser and report console errors, failed requests and a screenshot.

## Attach anything

- `@report.docx`, `@data.xlsx`, `@slides.pptx`, `@paper.pdf`, `@sales.csv`, `@notebook.ipynb`: turned
  into compact text on your computer (tables stay tables). Large documents are cut at about 6k tokens
  and the AI reads more pages, sheets or rows when it needs them.
- `@src/` attaches a folder digest (tree, file types, key files) instead of every file.
- Images (`.png .jpg .gif .webp .bmp`, up to 5 per message, 5 MB each): drag a screenshot into the
  terminal, use `@shot.png`, or Ctrl+V / `/paste-image`. `pip install "euron-code[images]"` adds
  resizing and clipboard paste.

## More

### Log in and accounts

```bash
euron login            # log in (or switch to another Euron account)
euron login --force    # switch without asking
euron whoami           # who you are, and your plan
euron logout           # remove the key from this computer
```

One login at a time: signing in on a new computer signs out the old one. If an account is already
running Euron Code in another terminal, you are asked whether to take over (`-p --takeover` in scripts).

The approval page approves for whichever Euron account is signed in on euron.one in that browser, so
to switch accounts sign in there with the other account first (or open the link in a private window).
If no browser opens (SSH, WSL), copy the link it prints. The key is kept in the system keychain, or in
`~/.euron/credentials.json` (readable only by you). To revoke a login, remove it at
https://euron.one/code-agent.

Optional extras: `pip install "euron-code[images]"` (image resizing, clipboard), `"euron-code[postgres]"`,
`"euron-code[mysql]"` (database explorer). Check the install with `euron --version` and `euron doctor`.

### Answering permission questions

| Key | Meaning |
|---|---|
| `y` | yes, once |
| `n` | no (you can then tell it what to do instead) |
| `a` | always allow this for the rest of the session |
| `p` | always allow commands starting the same way (e.g. every `npm test ...`) this session |
| `s` | always, and save the rule to `.euron/settings.local.json` |

### All commands

| Command | What it does |
|---|---|
| `/help` | list commands, your own commands and skills, and the shortcuts |
| `/status`, `/whoami` | account, key, API, model, mode, session, uptime, quota |
| `/usage` (`/users`) | quota per period, refill times, value, sessions, tasks, cache share, last 30 days |
| `/cost`, `/context` | what this session used; what fills the context |
| `/model [id]`, `/effort` | pick or set the model; reasoning effort |
| `/compact [focus]`, `/clear` | summarise to free context; start fresh |
| `/resume [id]`, `/rewind`, `/export [file]` | saved sessions; undo the last turn; save as Markdown |
| `/attach <paths>`, `/paste-image` | attach files, folders, documents, images to the next message |
| `/memory`, `/memory edit` | show or edit `EURON.md` memory |
| `/init` | map the repo and let the AI write `EURON.md` |
| `/rules`, `/rules new <name>` | list rules, create a rule file |
| `/skills`, `/skills new <name>` | list skills and commands, create a skill |
| `/hooks`, `/hooks new`, `/hooks enable` | list hooks, add an example, enable the set-up examples |
| `/review [focus]`, `/plan` | review uncommitted changes; plan mode |
| `/permissions` | rules and mode; `/permissions mode acceptEdits`, `/permissions allow "Bash(pytest:*)"` |
| `/config` | show settings; `/config set <key> <value> [--project]` |
| `/thinking show\|collapse\|hide`, `/todos`, `/doctor` | reasoning display, task list, setup check |
| `/login`, `/logout`, `/bug`, `/release-notes`, `/exit` | |
| `/<skill or command> [args]` | run one of your skills or custom commands |

### Plan mode

In plan mode Euron Code can only read and search: edits, shell commands and database writes are
refused. It explores and answers with a numbered plan. You then choose: `a` accept edits and go, `y`
go but ask before each change, or Enter to keep planning. The model cannot leave plan mode by itself.

### Rewind

Before Euron Code's file tools change a file, the original is kept in memory for that turn.
`/rewind` (or Esc Esc) puts the files back, removes the turn from the conversation and puts your
prompt back in the input line. Files you changed again after that turn are skipped (use
`/rewind --force`). Changes made by shell commands (`npm install`, a code generator) are not undone.

### Continue later

Every session is saved under `~/.euron/sessions/` (text only, without attached images).

```bash
euron --continue     # pick up the latest session in this folder
euron --resume       # choose from a list (or /resume inside a session)
```

### Project setup

`euron init` (or `euron --yes`, or Enter at the first-run question) creates, without overwriting
anything that exists:

```
EURON.md                      stack, commands, layout, entry points
.euron/rules/                 testing.md, git.md, security.md + python.md / node.md / go.md / rust.md
.euron/settings.json          allow rules for your test and lint commands and read-only git
.euron/hooks.example.json     example hooks, OFF until you run /hooks enable
.euron/commands/              /fix-tests, /commit, /pr
.gitignore                    + .euron/cache/ and .euron/settings.local.json
```

It is not offered in your home folder or a drive root, and a "no" is remembered.

## Memory: EURON.md

Put project instructions in `EURON.md` at the project root (commands to build and test, conventions,
things to avoid). Euron Code reads it at the start of every session, together with `EURON.md` files in
parent folders up to the git root and your personal `~/.euron/EURON.md`.

`/init` builds a map of the repository on your computer (detected stack, commands from the
manifests, top-level layout, entry points), then has the model confirm it and write a short
`EURON.md`: commands, layout, conventions and a compact repo map. It also offers to create
`.euron/rules/` and `.euron/settings.json` skeletons.

## Rules

Rules are short instructions for every session, kept in separate files:
`.euron/rules/*.md` (project, commit them) and `~/.euron/rules/*.md` (yours, all projects). They are
loaded after `EURON.md`. `/rules` lists them, `/rules new testing` creates
`.euron/rules/testing.md` (add `--user` for your own folder).

A rule can apply to some files only:

```markdown
---
paths: ["src/**/*.py", "tests/**"]
---
- Use type hints on every function.
- Tests use pytest fixtures, never unittest.
```

Such a rule is sent to the model the first time it reads or edits a matching file in the session,
not before. `**` matches any folders, `*` anything within a name; a pattern without `/` (like `*.py`)
matches the file name anywhere. HTML comments (`<!-- -->`) in rule files are never sent.

## Skills

A skill is a saved set of instructions for a job, in `.euron/skills/<name>/SKILL.md` (project) or
`~/.euron/skills/<name>/SKILL.md` (yours):

```markdown
---
name: deploy-check
description: Check the app is ready to deploy (tests, lint, migrations). Use before a release.
---
1. Run the tests and the linter...
```

Only the names and descriptions are in the model's context; it loads the full instructions with its
`skill` tool when a request matches. You can run one yourself: `/deploy-check staging`. `$ARGUMENTS`
in the body is replaced by what you type after the name. `/skills` lists them, `/skills new <name>`
creates one.

Built in: `/review` (reviews your uncommitted git changes), `/test-writer <target>` (writes and runs
tests with your project's framework) and `/explain-codebase [topic]`. A project skill with the same
name replaces a built-in one.

## Custom commands

A Markdown file in `.euron/commands/<name>.md` (or `~/.euron/commands/`) becomes `/<name>`. Its text is
sent as your message, with `$ARGUMENTS` replaced:

```markdown
---
description: Fix a GitHub issue
---
Read issue $ARGUMENTS with `gh issue view`, find the cause, fix it and add a test.
```

`/fix-issue 42` then does exactly that. Commands show up in `/help` and Tab completion.

## Hooks

Hooks are your own shell commands that run at fixed points. Put them in `settings.json`
(`~/.euron/settings.json` or `.euron/settings.json`):

```json
{
  "hooks": {
    "PostToolUse": [{"matcher": "Edit|Write", "command": "npx prettier --write .", "timeout": 30}],
    "PreToolUse":  [{"matcher": "Bash", "command": "python scripts/check_command.py"}],
    "UserPromptSubmit": [{"command": "git status --short"}],
    "SessionStart": [{"command": "git log --oneline -5"}],
    "Stop": [{"command": "python -m pytest -q || (echo tests fail 1>&2 && exit 2)"}]
  }
}
```

| Event | When | Exit code 2 |
|---|---|---|
| `SessionStart` | once, at the start | (stdout is added as context) |
| `UserPromptSubmit` | before your message is sent | drops the message; stderr is shown. stdout is added as context |
| `PreToolUse` | before a tool runs | blocks the tool; stderr goes to the model |
| `PostToolUse` | after a tool ran | stderr goes to the model as feedback |
| `Stop` | when the model finishes its answer | stderr goes to the model and it continues (at most twice) |

Any other non-zero exit is shown as a warning and blocks nothing. `matcher` is a regular expression
over the tool name; the common short names (`Edit`, `Write`, `MultiEdit`, `Read`, `Bash`, `Grep`, `Glob`,
`WebFetch`) and Euron Code names (`edit_file`, `bash`, ...) both work. The command runs in the project
folder with `cmd.exe` on Windows and `sh` elsewhere, and gets one JSON object on stdin: `event`,
`session_id`, `cwd`, `tool_name`, `tool_input`, `tool_output` (PostToolUse) or `prompt`. Environment:
`EURON_PROJECT_DIR`, `EURON_SESSION_ID`, `EURON_HOOK_EVENT`, `EURON_TOOL_NAME`, `EURON_FILE`.
`/hooks` lists them, `/hooks new` adds an example (format Python files with ruff after each edit).

**Project hooks need your OK.** A cloned repository could ship a harmful hook, so hooks from
`.euron/settings*.json` are shown to you once and only run after you trust them. The answer is
remembered in `~/.euron/trusted-hooks.json`; if the project's hooks change you are asked again. In
`-p` mode untrusted project hooks are skipped with a warning. Your own `~/.euron/settings.json` hooks
always run.

## Context and tokens (automatic)

Euron Code manages the conversation for you, with nothing to set up:

- **Always room to answer.** Each request leaves space for the reply; a conversation that is getting
  full is tidied up first.
- **Clearing.** Old tool output is replaced with one-line notes that say what to re-read (for example
  `read_file src/app.py lines 1-200`), so the agent keeps going without losing track.
- **Summary.** Long conversations are summarised: the task, decisions, files changed, commands and
  results, the last error and open todos.
- **Long answers and big edits.** An answer that gets cut off continues by itself. A huge edit that gets
  cut off is never applied half-way; the change is made in smaller steps instead.
- **Reasoning effort** is `medium` by default and `low` for quick follow-ups ("thanks", "continue");
  change it with `/effort low|medium|high`.
- **Reads.** Files are read in parts; a very large file returns an outline first. Re-reading an
  unchanged file returns a one-line note instead of the content.

`/cost` and `/context` show what this session used and what fills the context.

## Non-interactive use (scripts, CI)

```bash
euron -p "summarise what this repo does"
git diff | euron -p "review this diff"
euron -p "run the tests and fix failures" --allowed-tools "Edit,Bash(pytest:*)" --max-turns 20
euron -p "list the API routes" --output-format json
```

In `-p` mode nothing can ask you, so anything that needs permission is refused unless an allow rule
covers it (`--allowed-tools`, or settings). `--yolo` skips all prompts: only use it in a throwaway
folder or container.

`--permission-mode plan` gives a read-only run that ends with a plan.

With `--output-format json` the result also has `reuse` (one entry per planned component: `component`,
`decision`, `repo`, `license`), `reused` (files read from references) and `task_id`.

Exit codes: `0` ok, `1` error, `2` bad usage, `3` no Euron Plus / Super 30 access, `4` not logged in or
key rejected, `5` a token allowance used (day, week, month, year) or a cooldown, `6` `--max-turns` reached,
`130` interrupted.

## Database explorer

Euron Code can look at your app's database while it works. SQLite files inside the project work
directly (`look at app.db and tell me which tables have no index`). For Postgres or MySQL, name a
connection in your settings; `${VAR}` reads from the environment so passwords stay out of the file:

```bash
euron config set --project db.connections.app "postgresql://dev:${PGPASSWORD}@localhost:5432/app"
```

It is **read-only**: only `SELECT`, `WITH`, `EXPLAIN`, `SHOW`, `PRAGMA` and similar are allowed, and
the connection itself is opened read-only. To let it write (local dev databases only), run
`euron config set db.allowWrites true`; every write statement still asks you first.

## Settings

`euron config set <key> <value>` writes `~/.euron/settings.json` (add `--project` for
`.euron/settings.json` in the current folder). `euron config list` shows the merged result.

| Key | Default | |
|---|---|---|
| `model` | your account default | model id |
| `reasoning` | `collapse` | `show`, `collapse` or `hide` the model's thinking |
| `permissions.allow` / `permissions.deny` | `[]` | rules like `Edit`, `Bash(npm test:*)`, `WebFetch(domain:docs.python.org)`, `Read(~/notes/**)` |
| `permissions.defaultMode` | `default` | `default`, `acceptEdits` (edits inside the project need no prompt), `plan` (read-only) or `bypassPermissions` |
| `bashTimeout` | `120` | seconds before a command is stopped |
| `shell` | auto | PowerShell on Windows, bash/zsh elsewhere; or `cmd`, `bash`, a path |
| `autoCompact` | `true` | clear tool outputs from 50%, summarise at 70% (of the usable window) |
| `compactThreshold` | `0.7` | when to summarise the conversation |
| `microCompactThreshold` | `0.5` | when to start clearing tool outputs |
| `microCompactTarget` | `0.4` | clear until under this |
| `microCompactKeepSteps` | `1` | tool outputs of the last N steps are always kept |
| `outputReserve` | auto | tokens kept free for the answer (default min(8192, window/4)) |
| `reasoningEffort` | `medium` | `low`, `medium` or `high` (also `/effort`) |
| `attachmentMaxTokens` | `6000` | cap per attached document or folder digest |
| `toolOutputMaxChars` | `12000` | longer tool output is cut to head + tail |
| `hooks` | `{}` | see [Hooks](#hooks) |
| `webFetch` | `true` | allow the web page tool (it still asks per site) |
| `reuse.enabled` | `true` | look for reusable code before building (`--no-reuse` for one run) |
| `reuse.external` | `true` | also search permissively licensed GitHub projects, not only Euron's |
| `errorReporting` | `true` | send a short error report when something fails (see below) |
| `db.connections.<name>` | | database DSNs |

**Error reports.** When something fails, Euron Code sends Euron a short error report (the error kind and
code, the tool or command name, version and OS; never your prompts, code or secrets) so it can be fixed.
`/bug` shows your last ones. Turn it off with `euron config set errorReporting false` or
`EURON_NO_ERROR_REPORTS=1`.

Environment variables: `EURON_API_KEY` (use a key without logging in, for CI), `EURON_HOME` (instead of
`~/.euron`), `EURON_NO_BROWSER=1`.

## In VS Code

Open your project folder in VS Code, then open the integrated terminal (**Ctrl+`**, or
**Terminal > New Terminal**) and run `euron`. It works in the folder VS Code opened, and edits show up
in the editor straight away. Tips:

- On Windows the integrated terminal is PowerShell by default; Euron Code runs commands with
  PowerShell too. To use Git Bash instead: `euron config set shell bash`.
- If `euron` is not found after `pip install`, the Python `Scripts` folder is not on your PATH.
  Use `python -m euron_code`, or install with `pipx` (`pipx ensurepath`), then restart VS Code.
- Keep your edits saved before asking Euron Code to change the same file.

## Troubleshooting

| You see | What to do |
|---|---|
| `You don't have Euron Plus access...` | Euron Code needs Euron Plus or an active Super 30 enrolment: https://euron.one/plus |
| `not logged in` / `key was rejected` | run `euron login` again (keys can be revoked at euron.one/code-agent) |
| `servers are busy, retrying` | normal at peak times; it retries for you. If it gives up, try again in a few minutes |
| `Rate limit reached` | too many requests in one minute; it waits and retries |
| `today's token allowance` | you used today's limit; it resets at the time shown (midnight IST) |
| `this week's token allowance` | you used this week's limit; it resets at the time shown (Monday, midnight IST); month and year work the same way |
| `paused for you until` | too many rejected requests in a few minutes; wait until the time shown |
| `Images aren't available right now` | the image service is off; describe the picture in text |
| `untrusted project hook(s)` | the folder has hooks you have not approved; run `euron` there interactively once to review them |
| `The response stopped part-way` | the connection dropped mid-answer; nothing more was applied, send your message again |
| `euron: command not found` | see the VS Code tips above, or run `python -m euron_code` |
| garbled colours on old Windows consoles | use Windows Terminal or VS Code's terminal |

`euron doctor` checks Python, the connection, your login and plan, ripgrep (faster search; optional)
and the keychain.

## Privacy and safety

- Your code stays on your computer; the agent works on it from your terminal.
- Your key is never printed in full and never logged.
- Edits and commands ask first. Files outside the project folder always ask, even to read.
- Hooks are commands you configure; project hooks only run after you trust them.
- Text inside your files, web pages and command output is treated as data, not instructions.

### A cloned repo cannot take over your machine

A repository can ship `.euron/settings.json`, `EURON.md`, rules, skills and commands. Anything in them
that **loosens** a safety setting (allow rules, `bypassPermissions`, `shell`, `db.*`, raised limits) and
every instruction file for the agent only applies after you **trust the repo** once. Euron Code lists
exactly what the repo ships and asks: trust, ignore, or view it first. If any of it changes later (a
`git pull`), it asks again. Restrictions (deny rules, plan mode, lower limits) always apply. Your own
`~/.euron` settings are always trusted, and rules you approve with `s` are saved under `~/.euron`, not
in the repo. In `-p` mode an untrusted repo's settings are ignored with a warning; run `euron trust` once
in that folder (or `/trust` in a session) to trust it.

Even in bypass mode (`--dangerously-skip-permissions`) Euron Code still asks before: commands that
touch existing files outside the project (`cat ~/.ssh/id_rsa`, `rm -rf ~/Documents`), a short list of
destructive commands (`rm -rf /`, `git push --force`, `git reset --hard`, `curl ... | sh`, ...), and
web requests to your own machine or private networks (`localhost`, `192.168.x.x`, cloud metadata
addresses). Edits to `EURON.md` and `.euron/` always ask in acceptEdits mode.

Also: `grep` never shows the contents of secret-looking files (`.env`, keys, credentials); commands and
hooks never see `EURON_API_KEY`; transcripts are readable only by you (on macOS/Linux, mode 0600).

### It does not run away

The same failing call repeated 3 times makes Euron Code tell the model to change approach, and after 5
the request stops. Each request has a step budget (60 model steps, `maxStepsPerPrompt`); then it asks
whether to continue (`-p`: exit 6). After a change it reports what changed and what was run
(`Changed: calc.py | Ran: pytest -q (exit 0) | Not verified: none`), asks the model once to check an
unverified change, and checks the syntax of edited Python, JSON and JavaScript files.

## Licence

Copyright (c) 2026 Euron. All rights reserved. See `LICENSE`.
