{"_id":"@aetherdz/aethercode","_rev":"2-1a0459cd616ea0026c403e3d408b98a5","name":"@aetherdz/aethercode","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@aetherdz/aethercode","version":"0.1.0","keywords":["ai","cli","terminal","coding-assistant","llm","agent","aether","cross-platform"],"license":"MIT","_id":"@aetherdz/aethercode@0.1.0","maintainers":[{"name":"aetherdz","email":"abdozaik620@gmail.com"}],"homepage":"https://github.com/Aetherdz/aethercode#readme","bugs":{"url":"https://github.com/Aetherdz/aethercode/issues"},"bin":{"aether":"dist/index.js"},"dist":{"shasum":"669f060eac433cab20ed78aafa45aae78ee6be5c","tarball":"https://registry.npmjs.org/@aetherdz/aethercode/-/aethercode-0.1.0.tgz","fileCount":56,"integrity":"sha512-uIMS6+Qt6TCTwJerJOZaEWqjI4B6itKi61Hkt5BRlA37VJwtOYTvDFOJM3IGQfoVDOlXKWXRkScL9t1y7WTXbw==","signatures":[{"sig":"MEQCIGsF04DsLEz1psZW9WPLBS+3iXqG/Kmbk8RlhJIPCk6UAiBRBtf0Z5j3Ikp7CpDkeD0WAKm9EavxP3HdXEs3FQjTRQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":327482},"main":"dist/index.js","type":"module","engines":{"node":">=18"},"gitHead":"c1a98659bf839841c407c0b1c1cde9fc92f01fba","scripts":{"dev":"tsx src/index.ts","build":"tsc","start":"node dist/index.js","prepack":"npm run build","typecheck":"tsc --noEmit"},"_npmUser":{"name":"aetherdz","email":"abdozaik620@gmail.com"},"repository":{"url":"git+https://github.com/Aetherdz/aethercode.git","type":"git"},"_npmVersion":"12.0.2","description":"AETHER - a cross-platform terminal AI coding agent. Chat with LLMs, call tools, and write code straight from your terminal.","directories":{},"_nodeVersion":"24.18.1","allowScripts":{"esbuild@0.28.1":true},"dependencies":{"ai":"^7.0.56","ink":"^7.1.1","zod":"^3.25.76","react":"^19.2.8","dotenv":"^17.4.2","commander":"^15.0.0","picocolors":"^1.1.1","@ai-sdk/google":"^4.0.37","@ai-sdk/openai":"^4.0.34","@ai-sdk/anthropic":"^4.0.34","ollama-ai-provider":"^1.2.0","@ai-sdk/openai-compatible":"^3.0.25"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","typescript":"^5.9.0","@types/node":"^24.0.0","@types/react":"^19.2.18"},"_npmOperationalInternal":{"tmp":"tmp/aethercode_0.1.0_1786148440813_0.35636562743864997","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@aetherdz/aethercode","version":"0.2.0","description":"AETHER - a cross-platform terminal AI coding agent. Chat with LLMs, call tools, and write code straight from your terminal.","type":"module","main":"dist/index.js","bin":{"aether":"dist/index.js"},"repository":{"type":"git","url":"git+https://github.com/Aetherdz/aethercode.git"},"engines":{"node":">=18"},"keywords":["ai","cli","terminal","coding-assistant","llm","agent","aether","cross-platform"],"license":"MIT","scripts":{"build":"tsc","typecheck":"tsc --noEmit","start":"node dist/index.js","dev":"tsx src/index.ts","prepack":"npm run build"},"dependencies":{"@ai-sdk/anthropic":"^4.0.34","@ai-sdk/google":"^4.0.37","@ai-sdk/openai":"^4.0.34","@ai-sdk/openai-compatible":"^3.0.25","ai":"^7.0.56","commander":"^15.0.0","dotenv":"^17.4.2","ink":"^7.1.1","ollama-ai-provider":"^1.2.0","picocolors":"^1.1.1","react":"^19.2.8","zod":"^3.25.76"},"devDependencies":{"@types/node":"^24.0.0","@types/react":"^19.2.18","tsx":"^4.19.0","typescript":"^5.9.0"},"allowScripts":{"esbuild@0.28.1":true},"gitHead":"7db15e3906d043860b741742667c43ac529443a4","_id":"@aetherdz/aethercode@0.2.0","bugs":{"url":"https://github.com/Aetherdz/aethercode/issues"},"homepage":"https://github.com/Aetherdz/aethercode#readme","_nodeVersion":"24.18.1","_npmVersion":"12.0.2","dist":{"integrity":"sha512-UyDXKrMwr0UTPmnvr9DC9CFSlzdKDR5fJFOck3QVgbL5TG5R1jmKaMD5VSvB/oSNcVbovHQ61iU/8j609dMoWQ==","shasum":"ccc312cfa93aebf379780e49129ec2292a34dc62","tarball":"https://registry.npmjs.org/@aetherdz/aethercode/-/aethercode-0.2.0.tgz","fileCount":59,"unpackedSize":338516,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHzH8r/G5ZRvDoGREPC9V8LaF9DnaGPYR9oZjzM/moMwAiAP3yXoSO1FMyRqiNGHKSuoIZR5eS598iRgOile/7sSfg=="}]},"_npmUser":{"name":"aetherdz","email":"abdozaik620@gmail.com"},"directories":{},"maintainers":[{"name":"aetherdz","email":"abdozaik620@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/aethercode_0.2.0_1786152443676_0.6237052094477769"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-08T00:20:40.661Z","modified":"2026-08-08T01:27:23.974Z","0.1.0":"2026-08-08T00:20:40.972Z","0.2.0":"2026-08-08T01:27:23.838Z"},"bugs":{"url":"https://github.com/Aetherdz/aethercode/issues"},"license":"MIT","homepage":"https://github.com/Aetherdz/aethercode#readme","keywords":["ai","cli","terminal","coding-assistant","llm","agent","aether","cross-platform"],"repository":{"type":"git","url":"git+https://github.com/Aetherdz/aethercode.git"},"description":"AETHER - a cross-platform terminal AI coding agent. Chat with LLMs, call tools, and write code straight from your terminal.","maintainers":[{"name":"aetherdz","email":"abdozaik620@gmail.com"}],"readme":"<div align=\"center\">\n\n<img src=\"https://raw.githubusercontent.com/Aetherdz/aether-cli/main/docs/logo.svg\" alt=\"Aether logo\" width=\"500\">\n\n# Aether\n\n**Building tools that break assumptions.**\n\nA personal, cross-platform terminal AI coding agent. Chat with LLMs, call tools, and write code straight from your terminal — with a free, no-key default provider.\n\nBuilt by [Aetherdz](https://github.com/Aetherdz). Website: [aetherdz.github.io/aether-site](https://aetherdz.github.io/aether-site).\n\n</div>\n\n## Features\n\n- **Works instantly, zero setup** - ships with the free **OpenCode Zen** provider (OpenAI-compatible, no API key required). Run `aether` and start chatting.\n- **19 providers** - zen, openai, anthropic, google, deepseek, openrouter, ollama, groq, mistral, xai, cerebras, togetherai, fireworks, perplexity, moonshot, minimax, huggingface, lmstudio, github, plus any custom OpenAI-compatible endpoint.\n- **Cross-platform** - Windows, macOS, and Linux, from the start. An interactive Ink-based TUI (OLED-styled) is the default; `--no-tui` falls back to a lightweight `node:readline` REPL for dumb terminals and pipes.\n- **Low RAM** - lightweight streaming with ANSI colors and ASCII box-drawing; the classic `--no-tui` readline REPL keeps memory minimal on dumb terminals and pipes.\n- **Token-by-token streaming** - with a subtle status indicator and a token usage summary at the end of each turn.\n- **Agent tools** - `read_file`, `write_file`, `list_dir`, `grep_files`, `run_bash` (explicit confirmation required), and `web_fetch`.\n- **Swarm mode** - decompose a task into parallel subagents and get a boxed summary per subtask (analysis-only by default; opt-in git worktrees).\n- **Session persistence** - every conversation is saved as JSONL under `~/.config/aether/sessions/`.\n- **OAuth device login** - sign in with GitHub or Google the opencode way: a one-time code, your browser, zero API keys. `aether login-device github` / `aether login-device google`.\n- **Token-efficiency cache** - the exact same prompt in the exact same conversation context hits the disk cache and costs 0 tokens, so your free-tier quota lasts far longer.\n- **Smart fallback** - when the free provider is rate-limited, aether transparently falls back to local ollama, then any provider you have a key for. No dead stops.\n- **No emojis, ever** - a hard brand requirement. Plain ASCII and Unicode box-drawing only.\n\n## Install\n\nRequires Node.js 18+.\n\n```bash\nnpm install -g @aetherdz/aethercode\n```\n\nIf the global npm install fails (EACCES, read-only prefix), use the fallback one-liner:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Aetherdz/aethercode/main/install.sh | bash\n```\n\nOr run from source:\n\n```bash\ngit clone https://github.com/Aetherdz/aethercode.git\ncd aethercode\nnpm install\nnpm run build\nnpm install -g .   # makes the `aether` command available globally\naether --help\n```\n\nThe package is published on the npm registry as `@aetherdz/aethercode` — `aether upgrade` will keep you on the latest version. The marketing website lives in a separate repository: [Aetherdz/aether-site](https://github.com/Aetherdz/aether-site).\n\n## Free tier - how aether stretches it\n\nThe default zen provider is free but rate-limited (it can take hours to recover after heavy use). Aether stretches the free quota in three honest ways - no account rotation, no ToS games:\n\n1. **Disk cache** - the exact same prompt in the exact same conversation context is answered from `~/.config/aether/cache/` at **0 tokens**. The key includes the full conversation history, so a repeated question in a *changed* context is never served a stale answer. Content-addressed, TTL 7 days, capped at 500 entries / 64 MB. `aether cache stats`, `aether cache clear`.\n2. **Smart fallback chain** - on a rate-limit error aether automatically tries, in order: local **ollama** (free, unlimited, on your machine), **Gemini free tier**, then any provider you have a key for. You see a yellow notice for each hop. `aether` never just dies.\n3. **Transparent status** - `aether status` shows cache size; `aether cost` tracks usage. You always know where you stand.\n\nRun a local model for effectively unlimited free use:\n\n```bash\n# install ollama once, then point aether at it\nollama pull llama3.2\naether use ollama\n```\n\n## Security\n\n- **API keys never leave your machine.** Keys come from environment variables or the `aether login` command, which writes them to `~/.config/aether/.env` with 0600 permissions. The website only generates terminal commands - it never sees, stores, or transmits your keys.\n- **No hardcoded secrets** - nothing is committed to the repo.\n- `run_bash` always requires explicit `y/n` confirmation; non-interactive contexts deny by default.\n- `write_file` refuses paths outside the working directory.\n- Swarm analysis mode performs no file writes by default.\n\n## Quickstart\n\nThe interactive REPL works immediately with the free zen provider and no API key:\n\n```bash\naether\n```\n\n```\n┌──────────────────────────────────────────────────────────────────────────┐\n│ Aether  v0.1.0                                       terminal coding agent │\n│ zen/deepseek-v4-flash-free                cwd /path/to/your/project       │\n└──────────────────────────────────────────────────────────────────────────┘\n\naether > explain tail recursion\n```\n\nOne-shot questions:\n\n```bash\naether ask \"what is the difference between let and const in JavaScript?\"\n```\n\nSwitch providers/models:\n\n```bash\naether use zen/claude-sonnet-5\naether use openrouter\n```\n\n## Commands\n\n| Command | Description |\n| --- | --- |\n| `aether` | Interactive REPL chat with streaming, tools, and persisted history. |\n| `aether ask \"<question>\"` | One-shot non-interactive streamed answer. |\n| `aether use <provider>[/<model>]` | Set the default provider and model in config. |\n| `aether models [provider]` | List models. `zen` fetches the live list from `https://opencode.ai/zen/v1/models`. |\n| `aether providers` | List all providers with key status and the default marker. |\n| `aether swarm \"<task>\"` | Orchestrate parallel subagents for a task. |\n| `aether doctor` | Run environment diagnostics (config, keys, sessions). |\n| `aether status` | Show current configuration summary. |\n| `aether cost` | Show approximate usage totals from saved sessions. |\n| `aether keys` | Show which API keys are configured and where. |\n| `aether connect` | Interactive provider setup (opencode `/connect` style): pick a provider, paste a key, or start a device login — no manual config editing. |\n| `aether login <provider>` | Save an API key for a provider (stored in `~/.config/aether/.env`, 0600). |\n| `aether logout <provider>` | Remove the saved API key for a provider. |\n| `aether login-device github \\| google` | OAuth device-flow sign-in (opencode pattern): one-time code, no API key. |\n| `aether login-device list` | Show which device accounts are signed in. |\n| `aether logout-device <provider>` | Remove a device-flow sign-in. |\n| `aether cache stats \\| clear` | Inspect or clear the token-efficiency cache. |\n| `aether config [path\\|get <k> \\| set <k> <v> \\| providers]` | View or edit the config file. |\n| `aether alias [set\\|list\\|remove]` | Manage command aliases. |\n| `aether completions <bash\\|zsh\\|fish>` | Print shell completion script. |\n| `aether sessions list \\| show <id> \\| delete <id>` | Manage saved sessions. |\n| `aether --version` / `aether --help` | Version and help. |\n\n### REPL commands\n\n| Command | Description |\n| --- | --- |\n| `/quit`, `/exit` | Leave the session. |\n| `/clear` | Clear the screen. |\n| `/reset` | Forget conversation history. |\n| `/use <provider>[/<model>]` | Switch provider/model mid-session. |\n| `/help` | Show in-session help. |\n\n## Providers\n\nKeys are read from environment variables only. The `zen` provider needs no key and is the default, so the tool works with zero setup.\n\n| id | name | env var | key | pricing |\n| --- | --- | --- | --- | --- |\n| `zen` | OpenCode Zen | - | none needed | free |\n| `openai` | OpenAI | `OPENAI_API_KEY` | required | paid |\n| `anthropic` | Anthropic | `ANTHROPIC_API_KEY` | required | paid |\n| `google` | Google Gemini | `GOOGLE_GENERATIVE_AI_API_KEY` | required | free/paid |\n| `deepseek` | DeepSeek | `DEEPSEEK_API_KEY` | required | paid |\n| `openrouter` | OpenRouter | `OPENROUTER_API_KEY` | required | free/paid |\n| `groq` | Groq | `GROQ_API_KEY` | required | free/paid |\n| `mistral` | Mistral | `MISTRAL_API_KEY` | required | paid |\n| `xai` | xAI (Grok) | `XAI_API_KEY` | required | paid |\n| `cerebras` | Cerebras | `CEREBRAS_API_KEY` | required | paid |\n| `togetherai` | Together AI | `TOGETHER_API_KEY` | required | paid |\n| `fireworks` | Fireworks AI | `FIREWORKS_API_KEY` | required | paid |\n| `perplexity` | Perplexity | `PERPLEXITY_API_KEY` | required | paid |\n| `moonshot` | Moonshot AI (Kimi) | `MOONSHOT_API_KEY` | required | paid |\n| `minimax` | MiniMax | `MINIMAX_API_KEY` | required | paid |\n| `huggingface` | Hugging Face | `HF_TOKEN` | required | free/paid |\n| `lmstudio` | LM Studio (local) | - | local server | free |\n| `github` | GitHub Models | `GITHUB_TOKEN` | required | free/paid |\n| `ollama` | Ollama (local) | - | local server | free |\n| `custom` | any OpenAI-compatible endpoint | user-defined | optional | paid |\n\nSet keys in your shell profile (or a `.env` file loaded by dotenv). See `.env.example` — or run `aether connect` to set them interactively.\n\nIf a provider requires a key that is not set, aether automatically falls back to the free zen provider with a notice.\n\n### Device login (OAuth)\n\nGitHub and Google also work with **no API key at all**, using the OAuth 2.0 Device Authorization Grant (the opencode pattern): run `aether connect`, pick the device option, open the printed URL in any browser, enter the one-time code, and approve. The terminal polls automatically and stores the token in `~/.config/aether/device-tokens.json` (0600). `aether login-device github | google` does the same non-interactively.\n\n### Custom providers\n\nAdd an OpenAI-compatible endpoint in `~/.config/aether/config.json`:\n\n```json\n{\n  \"defaultProvider\": \"zen\",\n  \"defaultModel\": \"deepseek-v4-flash-free\",\n  \"providers\": {\n    \"custom\": [\n      {\n        \"name\": \"myendpoint\",\n        \"baseURL\": \"https://my-gateway.example.com/v1\",\n        \"apiKeyEnv\": \"MY_ENDPOINT_KEY\",\n        \"models\": [\"model-a\", \"model-b\"]\n      }\n    ]\n  }\n}\n```\n\n## Swarm mode\n\n`aether swarm` decomposes a task into 2-4 focused subtasks, runs them as parallel in-process subagents on the same provider/model (up to 4 concurrent), and prints a clean boxed summary per subtask.\n\n```bash\naether swarm \"design a REST API for a todo app: endpoints, auth, and data model\"\n```\n\n```\naether swarm decomposing task...\nplanned 3 subtasks on zen/deepseek-v4-flash-free\n[swarm] running 1/3: Define endpoints\n[swarm] running 2/3: Design auth flow\n[swarm] running 3/3: Model the data\n\nswarm results\n┌────────────────────────── subtask 1 Define endpoints ──────────────────────────┐\n│  REST API for a todo app:  ...                                                 │\n└────────────────────────────────────────────────────────────────────────────────┘\n```\n\nThe default swarm path is analysis/summary only - it writes no files. The opt-in `--worktree` flag wires git-worktree isolation (`git worktree add` under the system temp dir, confirmation required, must be inside a git repository) for subagents that need isolated file operations. This is v1-experimental.\n\n## Sessions\n\nEvery REPL conversation is appended, message by message, to `~/.config/aether/sessions/<ISO-timestamp>.jsonl`.\n\n```bash\naether sessions list\naether sessions show 2026-08-07T06-11-57-107Z\naether sessions delete 2026-08-07T06-11-57-107Z\n```\n\n## Configuration\n\n- Config file: `~/.config/aether/config.json` (override the directory with `AETHER_CONFIG_DIR`).\n- Created automatically on first run with `defaultProvider: zen` and `defaultModel: deepseek-v4-flash-free`.\n- Missing or corrupt config is recreated gracefully.\n\n## Security notes\n\n- API keys are never hardcoded and never committed. Keys come from environment variables only.\n- `run_bash` always requires an explicit `y/n` confirmation; non-interactive contexts deny by default.\n- `write_file` refuses paths outside the working directory.\n- Tool output and file access are scoped to the current working directory.\n- Swarm analysis mode performs no file writes by default.\n\n## Development\n\n```bash\nnpm run build      # tsc -> dist/\nnpm run typecheck  # tsc --noEmit\nnpm run dev        # run from source via tsx\n```\n\n## License\n\nMIT - Copyright (c) 2026 Aether-DZ. See [LICENSE](LICENSE).\n","readmeFilename":"README.md"}