euron-code 0.1.0__tar.gz → 0.2.0__tar.gz

{euron_code-0.1.0 → euron_code-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: euron-code
-Version: 0.1.0
+Version: 0.2.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>
@@ -139,23 +139,60 @@ Press **Esc** or **Ctrl-C** to stop a reply; the session stays open. **Ctrl-D**
 
 | Command | What it does |
 |---|---|
-| `/help` | list commands |
-| `/usage` | plan, tokens used today and your daily limit, reset time, last 30 days |
-| `/cost` | tokens used in this session |
+| `/help` | list commands, your own commands and skills, and the shortcuts |
+| `/usage` | today / this week / this month with limits, reset times, sessions, tasks, cache share, last 30 days |
+| `/cost` | tokens this session: sent, served from the server's cache, and saved automatically |
+| `/context` | what fills the context window (system, memory, rules, skills, tools, messages, tool results) |
 | `/model [id]` | show or switch the model |
 | `/compact [focus]` | summarise the conversation to free context |
 | `/clear` | start a fresh conversation |
+| `/resume [id]` | switch to a saved session |
+| `/rewind` | undo the last turn's file edits and drop it from the conversation (also **Esc Esc**) |
+| `/export [file]` | save the conversation as Markdown |
 | `/memory`, `/memory edit` | show or edit `EURON.md` memory |
-| `/init` | let Euron Code explore the repo and write `EURON.md` |
+| `/init` | map the repo and write `EURON.md`; offers `.euron/` skeletons |
+| `/rules`, `/rules new <name>` | list rules, create a rule file |
+| `/skills`, `/skills new <name>` | list skills and commands, create a skill |
+| `/hooks`, `/hooks new` | list hooks, add an example hook |
+| `/review [focus]` | review your uncommitted changes (built-in skill) |
+| `/plan` | toggle plan mode |
 | `/permissions` | show rules; `/permissions mode acceptEdits`, `/permissions allow "Bash(pytest:*)"` |
 | `/thinking show\|collapse\|hide` | how the model's reasoning is displayed |
 | `/todos` | the current task list |
 | `/doctor` | check your setup |
 | `/login`, `/logout`, `/exit` | |
-| `# some note` | save a note to memory (asks: project or user) |
+| `/<skill or command> [args]` | run one of your skills or custom commands |
 
-The bar at the bottom shows the model, tokens used this session, how full the context is, and how
-many tokens you have left today.
+The bar at the bottom shows the model, tokens used this session, how full the context is, how many
+tokens you have left (today or this week, whichever is tighter) and the permission mode.
+
+### Shortcuts
+
+| Type | What it does |
+|---|---|
+| `!npm test` | run a command yourself; the output goes into your next message |
+| `@src/app.py` | attach a file (or a folder listing) to your message; **Tab** completes paths |
+| `# note` | save a note to memory (asks: project or user) |
+| **Shift+Tab** | cycle the mode: default -> acceptEdits -> plan |
+| **Esc Esc** | on an empty prompt: rewind the last turn; otherwise clear the line |
+| **Esc** / **Ctrl-C** | interrupt a reply |
+| **Esc Enter** | new line |
+| **Ctrl-L** | clear the screen |
+| **Tab** | complete `/commands` and `@paths` |
+
+### Plan mode
+
+In plan mode (Shift+Tab twice, `/plan`, or `euron --permission-mode plan`) 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
 
@@ -172,9 +209,17 @@ euron --resume       # choose from a list
 euron usage
 ```
 
-shows your plan (Euron Plus / Super 30), tokens today out of your daily limit, what is left, when it
-resets (in your local time), all-time totals and a day-by-day table for the last 30 days. The daily
-allowance resets at midnight IST.
+(or `/usage` inside a session) shows, like Claude's usage page:
+
+- **Today**: a bar of tokens used against your daily limit, what is left, and when it resets.
+- **This week**: the same against your weekly limit, if your plan has one.
+- **This month**: tokens used since the 1st (no monthly cap).
+- For each period: requests, sessions, tasks (one task = one message you sent, with all the model
+  calls it took) and how much of your prompt was served from the server's cache.
+- A day-by-day table for the last 30 days.
+
+Reset times are shown in your local time. The day resets at midnight IST, the week on Monday at
+midnight IST. When the daily or weekly allowance is used up, Euron Code says so and when it resets.
 
 Euron Code sends one request at a time per student. When the servers are busy it waits and retries
 by itself, and tells you.
@@ -183,8 +228,125 @@ by itself, and tells you.
 
 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`. Run `/init` to have a first
-version written for you.
+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; Claude Code 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.
+
+## Saving tokens (automatic)
+
+The servers keep a cache of the start of each conversation, so a request that begins exactly like
+the last one is cheaper and faster. Euron Code is built around that, with nothing to set up:
+
+- The system prompt and tool list never change during a session. Changing data (date, git branch,
+  plan mode, hook output, `!` command output) goes at the end of your message instead.
+- Reading a file again that has not changed since the last read returns a one-line note
+  ("unchanged since your last read at turn 4") instead of the whole file.
+- Huge tool outputs are cut to their head and tail with a note (`toolOutputMaxChars`, default 12000).
+- When the context is 60% full, old tool outputs (older than the last 3 steps) become one-line stubs.
+  Only at 75% is the conversation summarised.
+- Path-scoped rules and skills are only loaded when needed.
+
+`/cost` and `/context` show what was sent, how much the server served from its cache, and how many
+tokens these measures kept out of the context.
 
 ## Non-interactive use (scripts, CI)
 
@@ -199,8 +361,10 @@ In `-p` mode nothing can ask you, so anything that needs permission is refused u
 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.
+
 Exit codes: `0` ok, `1` error, `2` bad usage, `3` no Euron Plus / Super 30 access, `4` not logged in or
-key rejected, `5` daily token allowance used, `6` `--max-turns` reached, `130` interrupted.
+key rejected, `5` daily or weekly token allowance used, `6` `--max-turns` reached, `130` interrupted.
 
 ## Database explorer
 
@@ -226,10 +390,15 @@ the connection itself is opened read-only. To let it write (local dev databases
 | `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) or `yolo` |
+| `permissions.defaultMode` | `default` | `default`, `acceptEdits` (edits inside the project need no prompt), `plan` (read-only) or `yolo` |
 | `bashTimeout` | `120` | seconds before a command is stopped |
 | `shell` | auto | PowerShell on Windows, bash/zsh elsewhere; or `cmd`, `bash`, a path |
-| `autoCompact` | `true` | summarise old turns when the context is 75% full |
+| `autoCompact` | `true` | clear old tool outputs at 60%, summarise at 75% |
+| `compactThreshold` | `0.75` | when to summarise the conversation |
+| `microCompactThreshold` | `0.6` | when to replace old tool outputs with stubs |
+| `microCompactKeepSteps` | `3` | tool outputs of the last N steps are always kept |
+| `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) |
 | `db.connections.<name>` | | database DSNs |
 
@@ -258,6 +427,8 @@ in the editor straight away. Tips:
 | `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) |
+| `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 |
@@ -271,6 +442,9 @@ and the keychain.
   reads. Nothing is uploaded anywhere else. There is no telemetry.
 - 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.
+- Each request carries a random session id and task id so your usage page can count sessions and
+  tasks. Nothing else about the conversation is stored by the gateway.
+- 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.
 
 ## Licence

euron_code-0.2.0/README.md

@@ -0,0 +1,391 @@
+# Euron Code
+
+An AI coding agent for your terminal, made for Euron students. Ask it to explain a codebase, fix a
+bug, write tests or build a feature: it reads your files, proposes edits, runs commands and checks
+its own work, asking you before it changes anything.
+
+Euron Code runs on your computer. Only the conversation goes to Euron's model servers.
+
+> **Requires Euron Plus or Super 30.** Euron Code is included with both. Get Plus at
+> https://euron.one/plus
+
+## Install
+
+Python 3.9 or newer, on Windows, macOS or Linux.
+
+```bash
+pip install euron-code
+# or, to keep it isolated from your projects:
+pipx install euron-code
+```
+
+Optional database drivers for the database explorer:
+
+```bash
+pip install "euron-code[postgres]"   # Postgres
+pip install "euron-code[mysql]"      # MySQL / MariaDB
+```
+
+Check the install with `euron --version` and `euron doctor`.
+
+## Log in
+
+```bash
+euron login
+```
+
+Your browser opens a Euron page that shows a code (for example `WXYZ-1234`). Check that it matches
+the code in your terminal and click **Approve**. The terminal finishes by itself. If no browser opens
+(SSH, WSL), copy the link it prints into any browser where you are logged in to euron.one.
+
+Your key is saved in the system keychain (Windows Credential Manager, macOS Keychain, Linux Secret
+Service). If there is no keychain it goes in `~/.euron/credentials.json`, readable only by you.
+
+```bash
+euron whoami     # who you are logged in as, and your plan
+euron logout     # remove the key from this computer
+```
+
+## Use it
+
+Open a terminal **in your project folder** and run:
+
+```bash
+euron
+```
+
+Then type what you want, for example:
+
+- `explain how authentication works in this project`
+- `the tests in tests/test_api.py fail, find out why and fix it`
+- `add input validation to the signup form and a test for it`
+
+Euron Code works step by step: it looks around, reads files, shows you a diff before each edit, and
+asks before running commands. Answer:
+
+| 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` |
+
+Press **Esc** or **Ctrl-C** to stop a reply; the session stays open. **Ctrl-D** or `/exit` quits.
+**Esc then Enter** inserts a newline.
+
+### Commands inside a session
+
+| Command | What it does |
+|---|---|
+| `/help` | list commands, your own commands and skills, and the shortcuts |
+| `/usage` | today / this week / this month with limits, reset times, sessions, tasks, cache share, last 30 days |
+| `/cost` | tokens this session: sent, served from the server's cache, and saved automatically |
+| `/context` | what fills the context window (system, memory, rules, skills, tools, messages, tool results) |
+| `/model [id]` | show or switch the model |
+| `/compact [focus]` | summarise the conversation to free context |
+| `/clear` | start a fresh conversation |
+| `/resume [id]` | switch to a saved session |
+| `/rewind` | undo the last turn's file edits and drop it from the conversation (also **Esc Esc**) |
+| `/export [file]` | save the conversation as Markdown |
+| `/memory`, `/memory edit` | show or edit `EURON.md` memory |
+| `/init` | map the repo and write `EURON.md`; offers `.euron/` skeletons |
+| `/rules`, `/rules new <name>` | list rules, create a rule file |
+| `/skills`, `/skills new <name>` | list skills and commands, create a skill |
+| `/hooks`, `/hooks new` | list hooks, add an example hook |
+| `/review [focus]` | review your uncommitted changes (built-in skill) |
+| `/plan` | toggle plan mode |
+| `/permissions` | show rules; `/permissions mode acceptEdits`, `/permissions allow "Bash(pytest:*)"` |
+| `/thinking show\|collapse\|hide` | how the model's reasoning is displayed |
+| `/todos` | the current task list |
+| `/doctor` | check your setup |
+| `/login`, `/logout`, `/exit` | |
+| `/<skill or command> [args]` | run one of your skills or custom commands |
+
+The bar at the bottom shows the model, tokens used this session, how full the context is, how many
+tokens you have left (today or this week, whichever is tighter) and the permission mode.
+
+### Shortcuts
+
+| Type | What it does |
+|---|---|
+| `!npm test` | run a command yourself; the output goes into your next message |
+| `@src/app.py` | attach a file (or a folder listing) to your message; **Tab** completes paths |
+| `# note` | save a note to memory (asks: project or user) |
+| **Shift+Tab** | cycle the mode: default -> acceptEdits -> plan |
+| **Esc Esc** | on an empty prompt: rewind the last turn; otherwise clear the line |
+| **Esc** / **Ctrl-C** | interrupt a reply |
+| **Esc Enter** | new line |
+| **Ctrl-L** | clear the screen |
+| **Tab** | complete `/commands` and `@paths` |
+
+### Plan mode
+
+In plan mode (Shift+Tab twice, `/plan`, or `euron --permission-mode plan`) 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/`.
+
+```bash
+euron --continue     # pick up the latest session in this folder
+euron --resume       # choose from a list
+```
+
+### Usage and limits
+
+```bash
+euron usage
+```
+
+(or `/usage` inside a session) shows, like Claude's usage page:
+
+- **Today**: a bar of tokens used against your daily limit, what is left, and when it resets.
+- **This week**: the same against your weekly limit, if your plan has one.
+- **This month**: tokens used since the 1st (no monthly cap).
+- For each period: requests, sessions, tasks (one task = one message you sent, with all the model
+  calls it took) and how much of your prompt was served from the server's cache.
+- A day-by-day table for the last 30 days.
+
+Reset times are shown in your local time. The day resets at midnight IST, the week on Monday at
+midnight IST. When the daily or weekly allowance is used up, Euron Code says so and when it resets.
+
+Euron Code sends one request at a time per student. When the servers are busy it waits and retries
+by itself, and tells you.
+
+## 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; Claude Code 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.
+
+## Saving tokens (automatic)
+
+The servers keep a cache of the start of each conversation, so a request that begins exactly like
+the last one is cheaper and faster. Euron Code is built around that, with nothing to set up:
+
+- The system prompt and tool list never change during a session. Changing data (date, git branch,
+  plan mode, hook output, `!` command output) goes at the end of your message instead.
+- Reading a file again that has not changed since the last read returns a one-line note
+  ("unchanged since your last read at turn 4") instead of the whole file.
+- Huge tool outputs are cut to their head and tail with a note (`toolOutputMaxChars`, default 12000).
+- When the context is 60% full, old tool outputs (older than the last 3 steps) become one-line stubs.
+  Only at 75% is the conversation summarised.
+- Path-scoped rules and skills are only loaded when needed.
+
+`/cost` and `/context` show what was sent, how much the server served from its cache, and how many
+tokens these measures kept out of 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.
+
+Exit codes: `0` ok, `1` error, `2` bad usage, `3` no Euron Plus / Super 30 access, `4` not logged in or
+key rejected, `5` daily or weekly token allowance used, `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 `yolo` |
+| `bashTimeout` | `120` | seconds before a command is stopped |
+| `shell` | auto | PowerShell on Windows, bash/zsh elsewhere; or `cmd`, `bash`, a path |
+| `autoCompact` | `true` | clear old tool outputs at 60%, summarise at 75% |
+| `compactThreshold` | `0.75` | when to summarise the conversation |
+| `microCompactThreshold` | `0.6` | when to replace old tool outputs with stubs |
+| `microCompactKeepSteps` | `3` | tool outputs of the last N steps are always kept |
+| `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) |
+| `db.connections.<name>` | | database DSNs |
+
+Environment variables: `EURON_CODE_API` (gateway URL, default
+`https://api.euron.one/api/v1/code-agent`), `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) |
+| `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 files are only sent as part of the conversation with Euron's model, and only what the agent
+  reads. Nothing is uploaded anywhere else. There is no telemetry.
+- 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.
+- Each request carries a random session id and task id so your usage page can count sessions and
+  tasks. Nothing else about the conversation is stored by the gateway.
+- 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.
+
+## Licence
+
+Copyright (c) 2026 Euron. All rights reserved. See `LICENSE`.

{euron_code-0.1.0 → euron_code-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "euron-code"
-version = "0.1.0"
+version = "0.2.0"
 description = "Euron Code: an agentic coding assistant in your terminal for Euron Plus and Super 30 students."
 readme = "README.md"
 requires-python = ">=3.9"