ion-code

A terminal coding agent. Install globally and run ion in any project.

Quick start

npm i -g ion-code
cd your-project
ion

On first run, ion creates ./.ion/ in your project and seeds default config files.

Configuration layout

All configuration lives in the project .ion folder:

.ion/
  .env              # API keys (gitignored, mode 0600)
  .gitignore        # contains ".env" as belt-and-suspenders
  models.json       # provider definitions, current model (ENV: refs only)
  preferences.json  # display/UX toggles
  agents/           # agent definitions (SYSTEM.md per folder)
  skills/           # user-authored skills (SKILL.md per folder)

Built-in skills (e.g. planning) ship with ion-code and are loaded automatically — they are not written to .ion/skills/. Only add skills to .ion/skills/ when you want custom project-specific workflows.

Editing configuration

| Goal | How | |------|-----| | Set API keys | Edit ./.ion/.env | | Change models | Edit ./.ion/models.json or use /models | | Change display toggles | Edit ./.ion/preferences.json, then run /refresh |

Use /refresh --global to apply project preferences and sync them to ~/.ion/preferences.json. /verbose and /reasoning still work as quick toggles.

Security

• Secrets stay out of git. The root .gitignore gets .ion/.env (and ./.ion/.gitignore also ignores .env). models.json uses ENV:VAR_NAME references only — never inline keys.
• The agent never reads .env files. Read, write, edit, grep, and glob tools block any path whose basename matches .env, .env.local, etc.