@moreai/code 0.0.0-stage → 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,28 @@
+More AI Code
+Copyright (c) 2026 More AI. All rights reserved.
+
+This software is proprietary. It is licensed, not sold.
+
+You may install the published package and use it to run More AI Code for your
+own work, subject to the More AI Terms of Service (https://more-ai.net/terms).
+
+You may not, except to the extent applicable law expressly permits it despite
+this restriction:
+  - copy, modify, merge, publish, distribute, sublicense or sell the software
+    or any part of it;
+  - reverse engineer, decompile, disassemble or otherwise attempt to derive
+    its source code, or extract its prompts, policies or other components for
+    use outside More AI Code;
+  - remove or alter this notice.
+
+Third-party components bundled with the software are distributed under their
+own licenses, reproduced in THIRD_PARTY_LICENSES.txt; those licenses govern
+those components only.
+
+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 NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS 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.

package/README.md

@@ -1,3 +1,337 @@
-# Temporary Holding Version
+# More AI Code (`moreai`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A terminal coding agent that runs on its own. The desktop app is optional: the CLI
+starts a bundled local engine when no More AI app is running.
+
+## Install the preview
+
+Requires Node.js 22 or newer on macOS, Linux or Windows.
+
+```sh
+npm install -g @moreai/code@beta
+moreai setup
+cd your-project
+moreai
+```
+
+The `beta` tag follows preview releases. To check for a new version and update
+the global installation:
+
+```sh
+moreai update
+moreai update --install
+moreai --version
+```
+
+`moreai update` checks the npm release tag and shows the available version;
+`--install` runs the global npm update. You can also update manually with
+`npm install -g @moreai/code@beta`. The CLI checks for updates in the
+interactive session and shows a quiet notice when a new version is available.
+
+If you received a packaged `.tgz` archive instead of installing from npm,
+install it with `npm install -g ./moreai-code-<version>.tgz`, then run the same
+`moreai setup` step. The archive includes the headless engine. Tarball installs
+do not receive updates until you install a newer archive or switch to the npm
+`beta` tag.
+
+`moreai setup` walks through a More AI account and an AI provider:
+
+- **AI provider** gives the agent a model on this computer. Connect an API key,
+  a local model (Ollama, LM Studio) or a supported provider subscription
+  through `moreai auth`. If a key is already in your environment
+  (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, …) the first run offers it at the top
+  of the list, and `moreai auth env` connects every one it finds. A More AI
+  account is not required to use your own provider.
+- **More AI account** is optional and adds what needs a server: cloud
+  sessions that keep working with this computer off (`moreai cloud`), session
+  and settings sync, More AI dictation, and Google services (Gmail, Calendar,
+  Drive) for the agent. Sign in with your email; approve the request on
+  another signed-in device or enter the emailed six-digit code. The account
+  session stays in the local engine, never in your shell history.
+- **External services** give the agent tools from a connector, such as an MCP
+  server. `moreai connectors` lists the catalog whenever you want one.
+
+You can run these steps separately at any time:
+
+```sh
+moreai login            # sign in to More AI
+moreai account          # show the signed-in account and plan
+moreai logout           # sign out; keeps your own provider connections
+moreai auth             # connect or change an AI provider
+moreai auth env         # connect the provider keys found in the environment
+moreai auth status      # list connected providers
+moreai connectors       # choose an external service
+moreai connectors list  # list connected services
+moreai doctor           # check the local engine and setup
+```
+
+When a provider signs in through the browser and you are on a remote machine
+over SSH, the sign-in page cannot reach back to the terminal on its own. The
+wizard prints the `ssh -L` command that forwards the sign-in port, or you can
+paste an API key instead.
+
+### External services from the terminal
+
+`moreai connectors` (or `/connectors` in a session) is one searchable list:
+what is connected — Google services from your More AI account (Gmail,
+Calendar, Meet, Tasks, Drive) and MCP servers alike, each with its state —
+then the whole catalog by category. Type to search, **Enter** connects (or
+fixes a connection that needs a new sign-in), **Space** turns a connected
+service on or off, **Ctrl+D** disconnects it (press twice). Google services
+belong to your More AI account, so a service connected on the desktop, the web
+or the phone is already on here. Choosing one while signed out explains why
+the account is needed and opens the sign-in right there; once you are in, the
+connection continues on its own. A service whose sign-in is kept with the
+account can also be connected on this computer only, without one. For a script or SSH
+session, use the commands directly:
+
+```sh
+moreai connectors catalog         # show service names and IDs
+moreai connectors add github      # connect a listed service
+moreai connectors add https://mcp.example.com/mcp  # connect a custom MCP URL
+moreai connectors list            # inspect connection IDs and status
+moreai connectors off ID          # keep a service but take its tools away
+moreai connectors on ID           # turn it back on
+moreai connectors remove ID       # disconnect by the ID shown in the list
+```
+
+For a service that needs a token, pipe it to `--token-stdin` so the secret does
+not appear in the command arguments or shell history:
+
+```sh
+printf '%s\n' "$MCP_TOKEN" | moreai connectors add github --token-stdin
+```
+
+Some services open a browser to finish sign-in. `moreai connectors list` shows
+whether each connection is ready. `moreai auth` remains the command for the
+AI model that answers your questions.
+
+### Sign in without an interactive terminal
+
+Starting sign-in from a script or SSH session requires an email argument:
+
+```sh
+moreai login you@example.com
+```
+
+If it sends an email code, pipe the **latest** six-digit code to the verification
+command. Piping keeps the code out of process arguments and shell history:
+
+```sh
+printf '%s\n' "$MOREAI_EMAIL_CODE" | moreai login you@example.com --code-stdin
+```
+
+If it returns a push approval challenge, the command prints its ID. Approve the
+matching confirmation code on another device, then run:
+
+```sh
+moreai login --challenge <id> --wait
+```
+
+To use an email code instead, run `moreai login --challenge <id> --fallback`,
+then pipe the code as above. No account token is printed by these commands.
+
+## Work in a project
+
+```sh
+moreai                       # interactive session in the current folder
+moreai "fix the failing test" # open a session and run a task
+moreai -c                    # continue the latest session for this folder
+moreai sessions              # list this folder's sessions
+moreai -p "add types"       # run once, print the result, exit
+git diff | moreai -p "review this diff"
+moreai -p --json "…"         # one JSON event per line
+```
+
+| Option | Meaning |
+| --- | --- |
+| `-p, --print` | Run once without the interactive UI |
+| `--json` | With `-p`, output machine-readable event lines |
+| `-c, --continue` | Continue this folder's newest session |
+| `--session <id>` | Resume a specific session |
+| `-m, --model <id>` | Choose a model for this run |
+| `--provider <id>` | Disambiguate the provider for a model |
+| `--mode <mode>` | `plan`, `read-only`, `accept-edits`, `auto`, or `full` |
+| `-C, --cwd <dir>` | Set the working folder |
+| `--cloud` | Run the task in a cloud session instead (see below) |
+| `--finish <how>` | With `--cloud`: `pr`, `push`, `branch` or `folder` |
+| `--detach` | With `--cloud`: start it and return without following |
+
+In the session, press **Enter** to send, **Ctrl+J** (or a trailing `\`) for a
+newline, **Esc** to interrupt, and **Shift+Tab** to change access mode. Use
+`/help` to see the available commands. You can type while the agent is working
+to steer its run. The status line shows the model, how much of its context
+window is left (yellow under 25 %, red under 10 %), the branch and the access
+mode.
+
+While the agent works, what it reads and searches folds into one
+**Explored** line, edits show as diffs, and its checklist stays above the input.
+
+### Helper agents
+
+The agent can split broad research across parallel **helper agents**. Each one
+gets its own line under the step that started it — what it was asked, what it
+is doing now, and when it finishes, its tool count, tokens and time with the
+first line of its report. The run's token total says how much of it the helpers
+spent. Helpers only read; the main agent makes the changes.
+
+Start a task with `@explore`, `@scout` or `@general` to hand it to that helper
+directly, even when automatic delegation is off:
+
+```sh
+moreai "@explore how does the billing webhook verify signatures?"
+```
+
+### Voice input
+
+**Ctrl+T** (or `/voice`) records from the microphone: a red dot, a timer and a
+level meter show it is listening. **Enter** or **Ctrl+T** stops and puts the
+text at the cursor — it is not sent, so you can read it first — and **Esc**
+throws the recording away. A recording stops by itself after two minutes.
+
+Transcription uses whatever the More AI app's dictation is set to: More AI
+dictation once you `/login`, your own transcription service, or an on-device
+model (Settings → Dictation in the app). The audio is recorded by this terminal,
+so the first time the system asks whether your terminal app may use the
+microphone. If a transcription fails, the recording is kept: **Ctrl+T** tries
+again.
+
+To record, `moreai` uses the ffmpeg that comes with the More AI app, or one of
+`ffmpeg`, `sox`, `parecord`, `arecord` on your PATH. `MOREAI_VOICE_RECORDER`
+names any other command that prints raw 16-bit 16 kHz mono audio on stdout
+(arguments separated by spaces).
+
+### Leaving a session
+
+**Ctrl+D** on an empty draft, **Ctrl+C** twice or `/quit` ends the session and
+hands the terminal back: the screen is cleared and one line remains with the
+command that resumes the session. Only the visible screen is cleared — what you
+ran before `moreai` stays in the scrollback — and the terminal gets its own
+title back. `MOREAI_KEEP_SCREEN=1` leaves the session on screen instead. A
+crash never clears the screen, so the error stays readable.
+
+### Choosing a model
+
+`/model` (or `/models`) opens the model picker: the current model, the models
+you pinned (shared with the desktop app's picker), your recent picks, then every
+connected provider — a large catalog such as OpenRouter grouped by vendor, with
+the context window and price where the provider reports them.
+
+- **Type** to search model names, providers and vendors (`sonnet`,
+  `or claude` for OpenRouter's Claude models, `anthropic`).
+- **↑ ↓** move, **PgUp PgDn** page, **← →** switch the provider tab.
+- **Enter** uses the model for this session and remembers it as your latest
+  pick, so a new session — here or in the desktop app — starts on it.
+- **Ctrl+F** pins or unpins a model; **Ctrl+A** connects another provider;
+  **Esc** clears the search, then closes.
+
+`/model <text>` switches immediately when the text names exactly one model
+(`/model glm-4.5`, `/model openrouter/anthropic/claude-sonnet-4.6`); anything
+else opens the picker with that search.
+
+### Editing and pasting
+
+The input box is a multi-line editor: **↑ ↓** move between lines (and reach your
+history from the first or last line of an empty or recalled draft),
+**Alt+← →** move by word, **Ctrl+A / Ctrl+E** jump to the line start or end,
+**Ctrl+U / Ctrl+K / Ctrl+W** delete. A long draft scrolls inside the box.
+
+A large paste (more than 8 lines or 800 characters) becomes a single
+`[Pasted text #1 · 200 lines]` item: **Backspace** removes it whole,
+**Ctrl+O** turns it back into editable text, and the agent receives the full
+text when you send. **Ctrl+C** clears the draft and keeps it in history; **Esc**
+twice clears it too.
+
+### Language
+
+The terminal agent speaks the same 35 languages as the desktop app and picks
+one without asking: `--lang` or `MOREAI_LANG` first, then your `/language`
+choice, then the desktop app's language, then the terminal's locale
+(`LC_ALL` / `LANG`) and finally the system language. `/language` lists them all
+(type to search; **Automatic** follows the app and the system), and
+`/language de` switches straight away. Slash commands, flags and key names stay
+in English everywhere, and `--json` output is always English.
+
+```sh
+moreai --lang ja        # this run only
+MOREAI_LANG=ru moreai   # the same, from the environment
+```
+
+## Cloud sessions
+
+With a More AI account, a task can run in the cloud instead of on this
+computer — it keeps going when you close the laptop, and you can follow it or
+answer it from the web app or your phone.
+
+```sh
+moreai cloud run "add tests for the parser"   # move this folder into a cloud session
+moreai --cloud "add tests for the parser"     # the same
+moreai cloud                                  # your cloud sessions and their state
+moreai cloud open <id>                        # the conversation and its link
+moreai cloud finish <id>                      # bring the work back again
+moreai cloud cancel <id>                      # stop the running task
+moreai cloud models                           # models a cloud run can use
+```
+
+`moreai cloud run` packages the folder as it is — your branch, commits and
+uncommitted changes, never files that look like secrets or are larger than
+25 MB — uploads it and starts the task, then follows it in the terminal: the
+current step, the answer when it is done. **Ctrl+C** stops following; the task
+keeps running (`--detach` returns straight away).
+
+When the task finishes, the work comes back on its own as a **new branch**
+`more-ai/<topic>-<id>`; your own branch and uncommitted edits are never
+touched. In a repository on GitHub or GitLab it is then pushed and a pull
+request is opened with your own `gh` / `glab` login; `--finish` chooses
+otherwise: `push`, `branch` (local only) or `folder` (copy the changed files
+into this folder, keeping your edits). The cloud runs on your plan's models,
+or on your own provider key if you uploaded it in the More AI app
+(Settings → Privacy); `-m` picks one of `moreai cloud models`.
+
+Inside a session, `/cloud` lists the cloud sessions (Enter shows one) and
+`/cloud <task>` moves the task there.
+
+## Engine and data
+
+`moreai doctor` and `/status` name the backend this build talks to. Installed
+packages use production (`api.more-ai.net`); only `MOREAI_ENV=dev`, at build or
+run time, points the CLI and its engine at the test tier, and the session's
+welcome screen then shows a `DEV` badge.
+
+
+Without the desktop app, `moreai` launches a bundled headless engine on this
+machine. Provider credentials are encrypted with a key kept in the operating
+system's keyring (macOS Keychain, Windows Credential Manager, or the Secret
+Service on Linux — GNOME Keyring or KWallet). A Linux server with no keyring
+service stores them unencrypted in a file only your user can read
+(`~/.config/More AI/secrets.json`), the way most command-line tools keep
+tokens. The CLI and VS Code can connect to the same running engine; sessions
+and settings persist across CLI restarts.
+
+If the desktop app is running with **External clients** enabled, the CLI attaches
+to its engine, so sessions appear on both surfaces. If the app is running with
+External clients disabled, enable it in **Settings → Agent tools**, or close the
+app so the CLI can start its own engine. `moreai doctor` reports this condition.
+
+## Usage analytics
+
+More AI collects usage analytics to find bugs and see which features work:
+commands you use, errors, and how agent runs go. With AI traces on (the
+default), the content of runs is included too, so failed runs can be debugged.
+API keys are never sent. The first interactive session asks once; you can
+change it at any time:
+
+```sh
+moreai analytics           # show the current setting
+moreai analytics usage     # analytics without conversation content
+moreai analytics off       # turn analytics off
+moreai analytics on        # analytics and AI traces
+```
+
+Inside a session, `/analytics` opens the same choice. `DO_NOT_TRACK=1` or
+`MOREAI_TELEMETRY=0` turns analytics off for any process that sees it. The
+setting belongs to this machine's engine, so it is shared with the More AI
+desktop app (Settings → Privacy) when both are installed.
+
+© 2026 More AI. All rights reserved. Proprietary software — see `LICENSE`;
+the open-source components it bundles are listed in `THIRD_PARTY_LICENSES.txt`.