From 322dcf98edb14c548460c507d5037bed4c907b55 Mon Sep 17 00:00:00 2001 From: Aayam Bansal Date: Sun, 5 Jul 2026 17:23:55 +0530 Subject: [PATCH] docs: Mintlify site for openscience.sh/docs --- docs/README.md | 4 + docs/agents.mdx | 484 +++++++++++++++++++++++++++++++++++++++ docs/atlas.mdx | 110 +++++++++ docs/cli.mdx | 465 +++++++++++++++++++++++++++++++++++++ docs/config.mdx | 475 ++++++++++++++++++++++++++++++++++++++ docs/contributing.mdx | 72 ++++++ docs/docs.json | 70 ++++++ docs/favicon.svg | 17 ++ docs/images/wordmark.svg | 17 ++ docs/index.mdx | 137 +++++++++++ docs/installation.mdx | 101 ++++++++ docs/mcp-servers.mdx | 408 +++++++++++++++++++++++++++++++++ docs/models.mdx | 185 +++++++++++++++ docs/permissions.mdx | 223 ++++++++++++++++++ docs/providers.mdx | 406 ++++++++++++++++++++++++++++++++ docs/rules.mdx | 166 ++++++++++++++ docs/share.mdx | 97 ++++++++ docs/skills.mdx | 194 ++++++++++++++++ docs/themes.mdx | 172 ++++++++++++++ docs/tools.mdx | 128 +++++++++++ docs/troubleshooting.mdx | 134 +++++++++++ 21 files changed, 4065 insertions(+) create mode 100644 docs/README.md create mode 100644 docs/agents.mdx create mode 100644 docs/atlas.mdx create mode 100644 docs/cli.mdx create mode 100644 docs/config.mdx create mode 100644 docs/contributing.mdx create mode 100644 docs/docs.json create mode 100644 docs/favicon.svg create mode 100644 docs/images/wordmark.svg create mode 100644 docs/index.mdx create mode 100644 docs/installation.mdx create mode 100644 docs/mcp-servers.mdx create mode 100644 docs/models.mdx create mode 100644 docs/permissions.mdx create mode 100644 docs/providers.mdx create mode 100644 docs/rules.mdx create mode 100644 docs/share.mdx create mode 100644 docs/skills.mdx create mode 100644 docs/themes.mdx create mode 100644 docs/tools.mdx create mode 100644 docs/troubleshooting.mdx diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..5472014 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,4 @@ +# OpenScience docs + +Mintlify documentation for OpenScience. Preview locally with `npx mint dev` from this directory. +Hosted at https://openscience.sh/docs. diff --git a/docs/agents.mdx b/docs/agents.mdx new file mode 100644 index 0000000..6b2814f --- /dev/null +++ b/docs/agents.mdx @@ -0,0 +1,484 @@ +--- +title: "Agents" +description: "Configure and use specialized agents." +icon: "bot" +keywords: ["agents", "subagents", "research", "plan", "biology", "physics", "ml", "custom agents"] +--- + +Agents are specialized assistants configured for specific tasks and workflows. Each agent has its own prompt, model, and tool access. You can switch between agents during a session or invoke them with an `@` mention. + +## Types + +There are two types of agents in OpenScience: primary agents and subagents. + +### Primary agents + +Primary agents are the main assistants you interact with directly. Cycle through them with the **Tab** key, or your configured `switch_agent` keybind. Tool access is configured via [permissions](/permissions); for example, Research has all tools enabled while Plan is restricted. + +OpenScience comes with two built-in primary agents, **Research** (the default) and **Plan**, plus the domain specialists **Biology**, **Physics**, and **ML** that can run as either primary agents or subagents. + +### Subagents + +Subagents are specialized assistants that primary agents invoke for specific tasks. You can also invoke them manually by `@` mentioning them in a message. + +OpenScience ships with built-in subagents that primary agents invoke automatically for specialized work: task (general-purpose), explore, literature-review, critique, reviewer, physics-critique, and write. + +## Built-in agents + +### Research + +_Mode_: `primary` + +Research is the default primary agent with all tools enabled. It is the standard harness for scientific research work such as literature review, data analysis, GPU compute, and synthesis, with full access to file operations and system commands. + +### Biology, Physics, and ML + +_Mode_: `all` + +Domain specialists for computational biology, computational physics, and machine learning. Each ships with a task-specific workflow prompt and can be used as your primary agent or invoked as a subagent. + +### Plan + +_Mode_: `primary` + +A restricted agent for planning and analysis. By default, the following are set to `ask`: + +- File edits: all writes, patches, and edits +- `bash`: all shell commands + +Use it when you want the LLM to analyze code, suggest changes, or create plans without modifying anything. + +### Task + +_Mode_: `subagent` + +A general-purpose agent for researching complex questions and executing multi-step tasks. Has full tool access (except todo), so it can make file changes when needed. Use it to run multiple units of work in parallel. + +### Explore + +_Mode_: `subagent` + +A fast, read-only agent for exploring codebases. It cannot modify files. Use it to find files by patterns, search code for keywords, or answer questions about the codebase. + +## Usage + +1. For primary agents, use the **Tab** key to cycle through them during a session, or your configured `switch_agent` keybind. + +2. Subagents can be invoked: + - Automatically by primary agents, based on the subagent's description. + - Manually, by `@` mentioning a subagent in your message: + + ```text + @explore help me search for this function + ``` + +3. When subagents create their own child sessions, you can move between the parent session and its child sessions in the workspace. Cycle forward with the `session_child_cycle` keybind and backward with `session_child_cycle_reverse`. + +## Configure + +You can customize the built-in agents or create your own, in JSON or markdown. + +### JSON + +Configure agents in your `openscience.json` config file: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "agent": { + "research": { + "mode": "primary", + "model": "anthropic/claude-sonnet-4-5", + "prompt": "{file:./prompts/research.txt}", + "tools": { + "write": true, + "edit": true, + "bash": true + } + }, + "code-reviewer": { + "description": "Reviews code for best practices and potential issues", + "mode": "subagent", + "model": "anthropic/claude-sonnet-4-5", + "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.", + "tools": { + "write": false, + "edit": false + } + } + } +} +``` + +### Markdown + +You can also define agents as markdown files. Place them in: + +- Global: `~/.config/openscience/agents/` +- Per project: `.openscience/agents/` + +```markdown ~/.config/openscience/agents/review.md +--- +description: Reviews code for quality and best practices +mode: subagent +model: anthropic/claude-sonnet-4-5 +temperature: 0.1 +tools: + write: false + edit: false + bash: false +--- + +You are in code review mode. Focus on: + +- Code quality and best practices +- Potential bugs and edge cases +- Performance implications +- Security considerations + +Provide constructive feedback without making direct changes. +``` + +The file name becomes the agent name: `review.md` creates a `review` agent. + +## Options + +### Description + +A brief description of what the agent does and when to use it. This is required: + +```json openscience.json +{ + "agent": { + "review": { + "description": "Reviews code for best practices and potential issues" + } + } +} +``` + +### Temperature + +Control the randomness of the LLM's responses. Lower values make responses more focused and deterministic; higher values increase variability: + +```json openscience.json +{ + "agent": { + "plan": { + "temperature": 0.1 + }, + "creative": { + "temperature": 0.8 + } + } +} +``` + +Typical ranges: + +- **0.0-0.2**: focused and deterministic, good for code analysis and planning +- **0.3-0.5**: balanced, good for general development tasks +- **0.6-1.0**: more varied, useful for brainstorming and exploration + +If no temperature is specified, OpenScience uses model-specific defaults: typically 0 for most models, 0.55 for Qwen models. + +### Max steps + +Limit the number of agentic iterations an agent can perform before it is forced to respond with text only. Useful for controlling costs: + +```json openscience.json +{ + "agent": { + "quick-thinker": { + "description": "Fast reasoning with limited iterations", + "prompt": "You are a quick thinker. Solve problems with minimal steps.", + "maxSteps": 5 + } + } +} +``` + +When the limit is reached, the agent receives a system prompt instructing it to summarize its work and list remaining tasks. If unset, the agent iterates until the model chooses to stop or you interrupt the session. + +### Disable + +Set `disable` to `true` to disable an agent: + +```json openscience.json +{ + "agent": { + "review": { + "disable": true + } + } +} +``` + +### Prompt + +Specify a custom system prompt file for the agent: + +```json openscience.json +{ + "agent": { + "review": { + "prompt": "{file:./prompts/code-review.txt}" + } + } +} +``` + +The path is relative to where the config file is located, so this works for both global and project config. + +### Model + +Override the model for a specific agent. Useful for using a faster model for planning and a more capable model for implementation: + +```json openscience.json +{ + "agent": { + "plan": { + "model": "anthropic/claude-haiku-4-5" + } + } +} +``` + +If you do not specify a model, primary agents use the [globally configured model](/config#models), and subagents use the model of the primary agent that invoked them. + +### Tools + +Control which tools are available to an agent by setting them to `true` or `false`: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "tools": { + "write": true, + "bash": true + }, + "agent": { + "plan": { + "tools": { + "write": false, + "bash": false + } + } + } +} +``` + +Agent-specific config overrides the global config. You can use wildcards to control multiple tools at once, for example to disable all tools from an MCP server: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "agent": { + "readonly": { + "tools": { + "mymcp_*": false, + "write": false, + "edit": false + } + } + } +} +``` + +See [Tools](/tools). + +### Permissions + +Configure what actions an agent can take. Each permission resolves to `"ask"`, `"allow"`, or `"deny"`. Agent permissions are merged with the global config, and agent rules take precedence: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "permission": { + "edit": "deny" + }, + "agent": { + "research": { + "permission": { + "edit": "ask" + } + } + } +} +``` + +You can set permissions for specific bash commands with glob patterns. Since the last matching rule takes precedence, put the `*` wildcard first and specific rules after: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "agent": { + "research": { + "permission": { + "bash": { + "*": "ask", + "git status *": "allow" + } + } + } + } +} +``` + +Permissions also work in markdown agents: + +```markdown ~/.config/openscience/agents/review.md +--- +description: Code review without edits +mode: subagent +permission: + edit: deny + bash: + "*": ask + "git diff": allow + "git log*": allow + "grep *": allow + webfetch: deny +--- + +Only analyze code and suggest changes. +``` + +See [Permissions](/permissions). + +### Mode + +Control how the agent can be used with the `mode` option: `primary`, `subagent`, or `all`. Defaults to `all`: + +```json openscience.json +{ + "agent": { + "review": { + "mode": "subagent" + } + } +} +``` + +### Hidden + +Hide a subagent from the `@` autocomplete menu with `hidden: true`. Useful for internal subagents that should only be invoked programmatically by other agents via the task tool: + +```json openscience.json +{ + "agent": { + "internal-helper": { + "mode": "subagent", + "hidden": true + } + } +} +``` + +This only affects visibility in the autocomplete menu. Hidden agents can still be invoked by the model via the task tool if permissions allow. Only applies to `mode: subagent` agents. + +### Task permissions + +Control which subagents an agent can invoke via the task tool with `permission.task`. Uses glob patterns: + +```json openscience.json +{ + "agent": { + "orchestrator": { + "mode": "primary", + "permission": { + "task": { + "*": "deny", + "orchestrator-*": "allow", + "code-reviewer": "ask" + } + } + } + } +} +``` + +When set to `deny`, the subagent is removed from the task tool description entirely, so the model does not attempt to invoke it. + +Rules are evaluated in order and the last matching rule wins. In the example above, `orchestrator-planner` matches both `*` (deny) and `orchestrator-*` (allow); since `orchestrator-*` comes after `*`, the result is `allow`. + +Users can always invoke any subagent directly via the `@` autocomplete menu, even if the agent's task permissions would deny it. + +### Additional options + +Any other options in your agent configuration are passed through directly to the provider as model options. This lets you use provider-specific parameters: + +```json openscience.json +{ + "agent": { + "deep-thinker": { + "description": "Agent that uses high reasoning effort for complex problems", + "model": "openai/gpt-5", + "reasoningEffort": "high", + "textVerbosity": "low" + } + } +} +``` + +These options are model and provider specific. Run `openscience models` to list available models. + +## Create agents + +Create a new agent interactively: + +```bash +openscience agent create +``` + +This command: + +1. Asks where to save the agent: global or project-specific. +2. Asks for a description of what the agent should do. +3. Generates an appropriate system prompt and identifier. +4. Lets you select which tools the agent can access. +5. Creates a markdown file with the agent configuration. + +## Examples + +### Documentation agent + +```markdown ~/.config/openscience/agents/docs-writer.md +--- +description: Writes and maintains project documentation +mode: subagent +tools: + bash: false +--- + +You are a technical writer. Create clear, comprehensive documentation. + +Focus on: + +- Clear explanations +- Proper structure +- Code examples +- User-friendly language +``` + +### Security auditor + +```markdown ~/.config/openscience/agents/security-auditor.md +--- +description: Performs security audits and identifies vulnerabilities +mode: subagent +tools: + write: false + edit: false +--- + +You are a security expert. Focus on identifying potential security issues. + +Look for: + +- Input validation vulnerabilities +- Authentication and authorization flaws +- Data exposure risks +- Dependency vulnerabilities +- Configuration security issues +``` diff --git a/docs/atlas.mdx b/docs/atlas.mdx new file mode 100644 index 0000000..8e3f25e --- /dev/null +++ b/docs/atlas.mdx @@ -0,0 +1,110 @@ +--- +title: "Atlas" +description: "Synthetic Sciences' managed platform for OpenScience: curated models, wallet billing, and cloud compute." +icon: "cloud" +keywords: ["atlas", "connect login", "wallet", "billing", "managed", "byok", "synsci"] +--- + +Atlas is Synthetic Sciences' managed platform for OpenScience. It gives you: + +- **Curated models**: a tested set of frontier models, served through the managed `synsci` provider and billed from a prepaid wallet. +- **Research graph**: your sessions, runs, and findings organized into a durable research map. +- **Cloud compute**: managed GPU compute for training jobs and experiment runs. + + +Atlas is completely optional. Bring-your-own-key (BYOK) is free, first-class, and needs no account. Configure your own provider API keys and OpenScience works fully without Atlas. + + +## Sign in + +Authenticate the CLI with: + +```bash +openscience connect login +``` + +This opens your browser to approve the device; the CLI then stores a long-lived `thk_` API key locally. On headless or CI machines, create a key in the dashboard and pass it directly: + +```bash +openscience connect login --key thk_... +``` + +You can also set the key in the `SYNSC_CLI_KEY` environment variable for non-interactive use. Manage your devices, API keys, and billing at [app.syntheticsciences.ai](https://app.syntheticsciences.ai/cli). + +Check the connection at any time: + +```bash +openscience connect status +``` + +List authenticated devices with `openscience connect devices`, and disconnect with `openscience connect logout`. + +## The two credential stores + +OpenScience keeps two kinds of credentials, and it is worth understanding the difference: + +1. **Local provider keys (BYOK).** Keys you add with `openscience auth login` or the `/connect` command are stored locally in `~/.local/share/openscience/auth.json`. They stay on your machine and are never uploaded anywhere. Requests made with them go straight to the provider. + +2. **The Atlas session.** `openscience connect login` stores a `thk_` session key locally and syncs *down*: it pulls the credentials for services you have connected in the dashboard onto your machine, so a new machine is ready to work after a single login. Re-run the sync at any time: + + ```bash + openscience connect sync + ``` + +When both stores have a credential for the same provider, **your local key wins**. Synced managed credentials never override a key you set yourself, whether it came from `auth.json` or a shell export. Requests on your own keys are direct to the provider and never metered by Atlas. + +## Models + +Managed models are served through the `synsci` provider. The [model ID](/models) in your config uses the format `synsci/`: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "model": "synsci/gpt-5-nano" +} +``` + +Run `/models` in the workspace to see the curated list. + +## Billing + +Atlas is billed from a prepaid wallet. Only **managed** calls, meaning requests running on Atlas-issued `thk_` credentials, draw from the wallet. Calls made with your own API keys (BYOK) or a first-party OAuth subscription (Claude Pro/Max, ChatGPT, GitHub Copilot) cost the wallet nothing and are never blocked by it. + +If your balance cannot cover a managed call, the session halts with an insufficient-credits message. Top up in the dashboard's Plan tab, or switch back to your own keys. + +Check your wallet balance and key routing from the CLI: + +```bash +openscience billing +``` + +And open the Plan tab to top up: + +```bash +openscience billing topup +``` + +Wallet top-ups are $50 or $200, one-time or recurring monthly. BYOK works on every plan. + +## Spend modes + +Key routing is per provider and automatic: your own key is used if one is set, otherwise the Atlas managed credential is used (and debits the wallet). You can pin the spend mode explicitly in your config: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "billing": { + "llm": "byok", + "compute": "byok" + } +} +``` + +- `llm`: `"managed"` bills LLM calls to your wallet; `"byok"` runs them on your own keys or subscriptions and is never billed. Unset means auto-detect from the resolved credential. +- `compute`: the same toggle for cloud compute. `"managed"` runs on Atlas-provisioned compute billed to your wallet; `"byok"` uses your own connected GPU providers. Defaults to `"byok"`. + +The spend toggle governs wallet gating, not which key is used. Key resolution (local key first, managed fallback) happens per provider; the `billing` setting controls whether managed usage is allowed to draw from the wallet. + +## BYOK + +You do not need an Atlas account to use OpenScience. Configure any [provider](/providers) with your own API key and all usage is billed by that provider directly, never by Synthetic Sciences. diff --git a/docs/cli.mdx b/docs/cli.mdx new file mode 100644 index 0000000..700b072 --- /dev/null +++ b/docs/cli.mdx @@ -0,0 +1,465 @@ +--- +title: "CLI reference" +description: "OpenScience CLI options, commands, and environment variables." +sidebarTitle: "CLI" +icon: "terminal" +keywords: ["cli", "commands", "flags", "environment variables", "run", "serve"] +--- + +The OpenScience CLI opens the workspace in your browser when run without any arguments: + +```bash +openscience +``` + +It also accepts the commands documented on this page, so you can interact with OpenScience programmatically: + +```bash +openscience run "Explain how closures work in JavaScript" +``` + +## workspace + +Open the OpenScience workspace in your browser: + +```bash +openscience [project] +``` + +### Flags + +| Flag | Short | Description | +| ------------ | ----- | ------------------------------------------ | +| `--continue` | `-c` | Continue the last session | +| `--session` | `-s` | Session ID to continue | +| `--prompt` | | Prompt to use | +| `--model` | `-m` | Model to use in the form of provider/model | +| `--agent` | | Agent to use | +| `--port` | | Port to listen on | +| `--hostname` | | Hostname to listen on | + +## Commands + +### agent + +Manage agents: + +```bash +openscience agent [command] +``` + +**create**: create a new agent with a custom system prompt and tool configuration. The command guides you through the setup: + +```bash +openscience agent create +``` + +**list**: list all available agents: + +```bash +openscience agent list +``` + +### auth + +Manage provider credentials: + +```bash +openscience auth [command] +``` + +**login**: configure API keys for any provider from the [Models.dev](https://models.dev) list. Credentials are stored locally in `~/.local/share/openscience/auth.json` and are never uploaded: + +```bash +openscience auth login +``` + +When OpenScience starts up it loads the providers from the credentials file, along with any keys defined in your environment or a `.env` file in your project. + +**list** (or `ls`): list authenticated providers and active provider environment variables: + +```bash +openscience auth list +``` + +**logout**: clear a provider from the credentials file: + +```bash +openscience auth logout +``` + +### connect + +Connect to the [Atlas](/atlas) dashboard: + +```bash +openscience connect [command] +``` + +**login**: authenticate the CLI with the dashboard. Opens your browser to approve the device; on headless or CI machines pass a key directly: + +```bash +openscience connect login +openscience connect login --key thk_... +``` + +| Flag | Description | +| -------------- | -------------------------------------------------------------- | +| `--key` | Paste a `thk_` API key directly (for headless or CI machines) | +| `--no-browser` | Skip the browser flow and paste a key manually | + +**status**: show connection status, backend, user, and synced services: + +```bash +openscience connect status +``` + +**sync**: pull credentials for dashboard-connected services down to this machine: + +```bash +openscience connect sync +``` + +**devices**: list authenticated devices: + +```bash +openscience connect devices +``` + +**logout**: disconnect from the dashboard: + +```bash +openscience connect logout +``` + +### billing + +Show your Atlas CLI wallet balance and how key routing works: + +```bash +openscience billing +``` + +**topup**: open the dashboard Plan tab to top up wallet credits: + +```bash +openscience billing topup +``` + +See [Atlas billing](/atlas#billing). + +### github + +Manage the GitHub agent for repository automation: + +```bash +openscience github [command] +``` + +**install**: install the GitHub agent in your repository. Sets up the GitHub Actions workflow and guides you through configuration: + +```bash +openscience github install +``` + +**run**: run the GitHub agent, typically from GitHub Actions: + +```bash +openscience github run +``` + +| Flag | Description | +| --------- | -------------------------------------- | +| `--event` | GitHub mock event to run the agent for | +| `--token` | GitHub personal access token | + +### mcp + +Manage Model Context Protocol servers: + +```bash +openscience mcp [command] +``` + +**add**: add a local or remote MCP server to your configuration: + +```bash +openscience mcp add +``` + +**list** (or `ls`): list configured MCP servers and their connection status: + +```bash +openscience mcp list +``` + +**auth**: authenticate with an OAuth-enabled MCP server. Without a server name, you are prompted to select from available OAuth-capable servers: + +```bash +openscience mcp auth [name] +openscience mcp auth list +``` + +**logout**: remove OAuth credentials for an MCP server: + +```bash +openscience mcp logout [name] +``` + +**debug**: debug OAuth connection issues for an MCP server: + +```bash +openscience mcp debug +``` + +See [MCP servers](/mcp-servers). + +### models + +List all available models from configured providers, in the format `provider/model`: + +```bash +openscience models [provider] +``` + +This is useful for figuring out the exact model name to use in [your config](/config). Pass a provider ID to filter: + +```bash +openscience models anthropic +``` + +| Flag | Description | +| ----------- | ------------------------------------------------------------- | +| `--refresh` | Refresh the models cache from Models.dev | +| `--verbose` | More verbose model output (includes metadata like costs) | + +Use `--refresh` when new models have been added to a provider and you want to see them in OpenScience. + +### run + +Run OpenScience in non-interactive mode by passing a prompt directly: + +```bash +openscience run [message..] +``` + +This is useful for scripting and automation: + +```bash +openscience run Explain the use of context in Go +``` + +You can attach to a running `openscience serve` instance to avoid MCP server cold boot times on every run: + +```bash +# Start a headless server in one terminal +openscience serve + +# In another terminal, run commands that attach to it +openscience run --attach http://localhost:4096 "Explain async/await in JavaScript" +``` + +| Flag | Short | Description | +| ------------ | ----- | ------------------------------------------------------------------ | +| `--command` | | The command to run, use message for args | +| `--continue` | `-c` | Continue the last session | +| `--session` | `-s` | Session ID to continue | +| `--share` | | Share the session | +| `--model` | `-m` | Model to use in the form of provider/model | +| `--agent` | | Agent to use | +| `--file` | `-f` | File(s) to attach to message | +| `--format` | | Format: default (formatted) or json (raw JSON events) | +| `--title` | | Title for the session (uses truncated prompt if no value provided) | +| `--attach` | | Attach to a running openscience server (e.g., http://localhost:4096) | +| `--port` | | Port for the local server (defaults to random port) | + +### serve + +Start a headless OpenScience server for API access: + +```bash +openscience serve +``` + +This starts an HTTP server that provides API access without a browser interface. Set `OPENSCIENCE_SERVER_PASSWORD` to enable HTTP basic auth (username defaults to `openscience`). + +| Flag | Description | +| ------------ | ------------------------------------------ | +| `--port` | Port to listen on | +| `--hostname` | Hostname to listen on | +| `--mdns` | Enable mDNS discovery | +| `--cors` | Additional browser origin(s) to allow CORS | + +### session + +Manage OpenScience sessions: + +```bash +openscience session [command] +``` + +**list**: list all sessions: + +```bash +openscience session list +``` + +| Flag | Short | Description | +| ------------- | ----- | ------------------------------------ | +| `--max-count` | `-n` | Limit to N most recent sessions | +| `--format` | | Output format: table or json (table) | + +### stats + +Show token usage and cost statistics for your sessions: + +```bash +openscience stats +``` + +| Flag | Description | +| ----------- | ---------------------------------------------------------------------------- | +| `--days` | Show stats for the last N days (all time) | +| `--tools` | Number of tools to show (all) | +| `--models` | Show model usage breakdown (hidden by default). Pass a number to show top N | +| `--project` | Filter by project (all projects, empty string: current project) | + +### export + +Export session data as JSON: + +```bash +openscience export [sessionID] +``` + +If you do not provide a session ID, you are prompted to select from available sessions. + +### import + +Import session data from a JSON file or an OpenScience share URL: + +```bash +openscience import +``` + +```bash +openscience import session.json +openscience import https://syntheticsciences.ai/s/abc123 +``` + +### web + +Start a headless OpenScience server and open the web interface: + +```bash +openscience web +``` + +Set `OPENSCIENCE_SERVER_PASSWORD` to enable HTTP basic auth (username defaults to `openscience`). + +| Flag | Description | +| ------------ | ------------------------------------------ | +| `--port` | Port to listen on | +| `--hostname` | Hostname to listen on | +| `--mdns` | Enable mDNS discovery | +| `--cors` | Additional browser origin(s) to allow CORS | + +### acp + +Start an ACP (Agent Client Protocol) server that communicates via stdin/stdout using nd-JSON: + +```bash +openscience acp +``` + +| Flag | Description | +| ------------ | --------------------- | +| `--cwd` | Working directory | +| `--port` | Port to listen on | +| `--hostname` | Hostname to listen on | + +### uninstall + +Uninstall OpenScience and remove all related files: + +```bash +openscience uninstall +``` + +| Flag | Short | Description | +| --------------- | ----- | ------------------------------------------- | +| `--keep-config` | `-c` | Keep configuration files | +| `--keep-data` | `-d` | Keep session data and snapshots | +| `--dry-run` | | Show what would be removed without removing | +| `--force` | `-f` | Skip confirmation prompts | + +### upgrade + +Update OpenScience to the latest version or a specific version: + +```bash +openscience upgrade [target] +``` + +```bash +openscience upgrade # latest +openscience upgrade v0.1.48 # specific version +``` + +| Flag | Short | Description | +| ---------- | ----- | ----------------------------------------------------------------- | +| `--method` | `-m` | The installation method that was used: curl, npm, pnpm, bun, brew | + +## Global flags + +| Flag | Short | Description | +| -------------- | ----- | ------------------------------------ | +| `--help` | `-h` | Display help | +| `--version` | `-v` | Print version number | +| `--print-logs` | | Print logs to stderr | +| `--log-level` | | Log level (DEBUG, INFO, WARN, ERROR) | + +## Environment variables + +| Variable | Type | Description | +| ---------------------------------------- | ------- | ---------------------------------------------------- | +| `OPENSCIENCE_AUTO_SHARE` | boolean | Automatically share sessions | +| `OPENSCIENCE_GIT_BASH_PATH` | string | Path to Git Bash executable on Windows | +| `OPENSCIENCE_CONFIG` | string | Path to config file | +| `OPENSCIENCE_CONFIG_DIR` | string | Path to config directory | +| `OPENSCIENCE_CONFIG_CONTENT` | string | Inline JSON config content | +| `OPENSCIENCE_DISABLE_AUTOUPDATE` | boolean | Disable automatic update checks | +| `OPENSCIENCE_DISABLE_PRUNE` | boolean | Disable pruning of old data | +| `OPENSCIENCE_DISABLE_TERMINAL_TITLE` | boolean | Disable automatic terminal title updates | +| `OPENSCIENCE_PERMISSION` | string | Inline JSON permissions config | +| `OPENSCIENCE_DISABLE_DEFAULT_PLUGINS` | boolean | Disable default plugins | +| `OPENSCIENCE_DISABLE_LSP_DOWNLOAD` | boolean | Disable automatic LSP server downloads | +| `OPENSCIENCE_ENABLE_EXPERIMENTAL_MODELS` | boolean | Enable experimental models | +| `OPENSCIENCE_DISABLE_AUTOCOMPACT` | boolean | Disable automatic context compaction | +| `OPENSCIENCE_DISABLE_CLAUDE_CODE` | boolean | Disable reading from `.claude` (prompt + skills) | +| `OPENSCIENCE_DISABLE_CLAUDE_CODE_PROMPT` | boolean | Disable reading `~/.claude/CLAUDE.md` | +| `OPENSCIENCE_DISABLE_CLAUDE_CODE_SKILLS` | boolean | Disable loading `.claude/skills` | +| `OPENSCIENCE_CLIENT` | string | Client identifier (defaults to `cli`) | +| `OPENSCIENCE_ENABLE_EXA` | boolean | Enable Exa web search tools | +| `OPENSCIENCE_SERVER_PASSWORD` | string | Enable basic auth for `serve`/`web` | +| `OPENSCIENCE_SERVER_USERNAME` | string | Override basic auth username (default `openscience`) | + +### Experimental + +These environment variables enable experimental features that may change or be removed: + +| Variable | Type | Description | +| -------------------------------------------------- | ------- | ---------------------------------------- | +| `OPENSCIENCE_EXPERIMENTAL` | boolean | Enable all experimental features | +| `OPENSCIENCE_EXPERIMENTAL_ICON_DISCOVERY` | boolean | Enable icon discovery | +| `OPENSCIENCE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT` | boolean | Disable copy on select | +| `OPENSCIENCE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS` | number | Default timeout for bash commands in ms | +| `OPENSCIENCE_EXPERIMENTAL_OUTPUT_TOKEN_MAX` | number | Max output tokens for LLM responses | +| `OPENSCIENCE_EXPERIMENTAL_FILEWATCHER` | boolean | Enable file watcher for entire dir | +| `OPENSCIENCE_EXPERIMENTAL_OXFMT` | boolean | Enable oxfmt formatter | +| `OPENSCIENCE_EXPERIMENTAL_LSP_TOOL` | boolean | Enable experimental LSP tool | +| `OPENSCIENCE_EXPERIMENTAL_DISABLE_FILEWATCHER` | boolean | Disable file watcher | +| `OPENSCIENCE_EXPERIMENTAL_EXA` | boolean | Enable experimental Exa features | +| `OPENSCIENCE_EXPERIMENTAL_LSP_TY` | boolean | Enable experimental LSP type checking | +| `OPENSCIENCE_EXPERIMENTAL_MARKDOWN` | boolean | Enable experimental markdown features | +| `OPENSCIENCE_EXPERIMENTAL_PLAN_MODE` | boolean | Enable plan mode | diff --git a/docs/config.mdx b/docs/config.mdx new file mode 100644 index 0000000..834a8d6 --- /dev/null +++ b/docs/config.mdx @@ -0,0 +1,475 @@ +--- +title: "Config" +description: "Configure OpenScience with the openscience.json config file." +icon: "settings" +keywords: ["config", "openscience.json", "jsonc", "schema", "precedence"] +--- + +You can configure OpenScience using a JSON config file. + +## Format + +OpenScience supports both JSON and JSONC (JSON with comments): + +```jsonc openscience.jsonc +{ + "$schema": "https://openscience.sh/config.json", + // Theme configuration + "theme": "openscience", + "model": "anthropic/claude-sonnet-4-5", + "autoupdate": true, +} +``` + +The config file has a schema defined at [`openscience.sh/config.json`](https://openscience.sh/config.json). Your editor can validate and autocomplete based on the schema. + +## Locations + +Config files are merged together, not replaced. Later configs override earlier ones only for conflicting keys; non-conflicting settings from all configs are preserved. + +Config sources are loaded in this order (later sources override earlier ones): + +1. Remote config (from `.well-known/openscience`): organizational defaults +2. Global config (`~/.config/openscience/openscience.json`): user preferences +3. Custom config (`OPENSCIENCE_CONFIG` env var): custom overrides +4. Project config (`openscience.json` in project): project-specific settings +5. `.openscience` directories: agents, commands, plugins +6. Inline config (`OPENSCIENCE_CONFIG_CONTENT` env var): runtime overrides + + +The `.openscience` and `~/.config/openscience` directories use plural names for subdirectories: `agents/`, `commands/`, `modes/`, `plugins/`, `skills/`, `tools/`, and `themes/`. Singular names (for example `agent/`) are also supported for backwards compatibility. + + +### Remote + +Organizations can provide default configuration via a `.well-known/openscience` endpoint. It is fetched automatically when you authenticate with a provider that supports it, and serves as the base layer that all other config sources can override. + +For example, if your organization provides MCP servers that are disabled by default, you can enable specific servers in your local config: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "mcp": { + "jira": { + "type": "remote", + "url": "https://jira.example.com/mcp", + "enabled": true + } + } +} +``` + +### Global + +Place your global config in `~/.config/openscience/openscience.json`. Use it for user-wide preferences like themes, providers, or your default model. + +### Per project + +Add `openscience.json` in your project root. Project config has the highest precedence among standard config files. When OpenScience starts, it looks for a config file in the current directory and traverses up to the nearest Git directory. + +Project config is safe to check into Git and uses the same schema as the global one. + +### Custom path + +Specify a custom config file path with the `OPENSCIENCE_CONFIG` environment variable: + +```bash +export OPENSCIENCE_CONFIG=/path/to/my/custom-config.json +openscience run "Hello world" +``` + +Custom config is loaded between global and project configs. + +### Custom directory + +Specify a custom config directory with `OPENSCIENCE_CONFIG_DIR`. It is searched for agents, commands, modes, and plugins just like the standard `.openscience` directory, and follows the same structure: + +```bash +export OPENSCIENCE_CONFIG_DIR=/path/to/my/config-directory +openscience run "Hello world" +``` + +The custom directory is loaded after the global config and `.openscience` directories, so it can override their settings. + +## Options + +### Models + +Configure providers and models through the `provider`, `model`, and `small_model` options: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "provider": {}, + "model": "anthropic/claude-sonnet-4-5", + "small_model": "anthropic/claude-haiku-4-5" +} +``` + +The `small_model` option configures a separate model for lightweight tasks like title generation. By default, OpenScience tries to use a cheaper model from your provider if one is available, otherwise it falls back to your main model. + +Provider options can include `timeout` and `setCacheKey`: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "provider": { + "anthropic": { + "options": { + "timeout": 600000, + "setCacheKey": true + } + } + } +} +``` + +- `timeout`: request timeout in milliseconds (default: 300000). Set to `false` to disable. +- `setCacheKey`: ensure a cache key is always set for the provider. + +See [Models](/models) and [Providers](/providers) for details, including provider-specific options like the AWS `region`, `profile`, and `endpoint` settings for [Amazon Bedrock](/providers#amazon-bedrock). + +### Themes + +Set the workspace theme through the `theme` option: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "theme": "tokyonight" +} +``` + +See [Themes](/themes). + +### Agents + +Configure specialized agents through the `agent` option: + +```jsonc openscience.jsonc +{ + "$schema": "https://openscience.sh/config.json", + "agent": { + "code-reviewer": { + "description": "Reviews code for best practices and potential issues", + "model": "anthropic/claude-sonnet-4-5", + "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.", + "tools": { + // Disable file modification tools for review-only agent + "write": false, + "edit": false, + }, + }, + }, +} +``` + +You can also define agents using markdown files in `~/.config/openscience/agents/` or `.openscience/agents/`. See [Agents](/agents). + +### Default agent + +Set the default agent with the `default_agent` option. This determines which agent is used when none is explicitly specified: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "default_agent": "plan" +} +``` + +The default agent must be a primary agent (not a subagent). It can be a built-in agent like `"research"`, `"biology"`, `"physics"`, `"ml"`, or `"plan"`, or a [custom agent](/agents) you have defined. If the specified agent does not exist or is a subagent, OpenScience falls back to `"research"` with a warning. + +This setting applies across all interfaces: the browser workspace, the CLI (`openscience run`), and the GitHub agent. + +### Permissions + +By default, OpenScience allows all operations without requiring explicit approval. Change this with the `permission` option: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "permission": { + "edit": "ask", + "bash": "ask" + } +} +``` + +See [Permissions](/permissions). + +### Sharing + +Configure the [share](/share) feature through the `share` option: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "share": "manual" +} +``` + +- `"manual"`: allow manual sharing via commands (default) +- `"auto"`: automatically share new conversations +- `"disabled"`: disable sharing entirely + +### Commands + +Configure custom commands for repetitive tasks through the `command` option: + +```jsonc openscience.jsonc +{ + "$schema": "https://openscience.sh/config.json", + "command": { + "test": { + "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.", + "description": "Run tests with coverage", + "agent": "research", + "model": "anthropic/claude-haiku-4-5", + }, + "component": { + "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.", + "description": "Create a new component", + }, + }, +} +``` + +You can also define commands using markdown files in `~/.config/openscience/commands/` or `.openscience/commands/`. + +### Server + +Configure the `openscience serve` and `openscience web` commands through the `server` option: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "server": { + "port": 4096, + "hostname": "0.0.0.0", + "mdns": true, + "cors": ["http://localhost:5173"] + } +} +``` + +- `port`: port to listen on. +- `hostname`: hostname to listen on. When `mdns` is enabled and no hostname is set, defaults to `0.0.0.0`. +- `mdns`: enable mDNS service discovery so other devices on the network can discover your OpenScience server. +- `cors`: additional origins to allow for CORS when using the HTTP server from a browser-based client. Values must be full origins (scheme + host + optional port), for example `https://app.example.com`. + +### Autoupdate + +OpenScience automatically downloads new updates when it starts up. Disable this with the `autoupdate` option: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "autoupdate": false +} +``` + +Set `autoupdate` to `"notify"` to be notified about new versions without installing them. This only works if OpenScience was not installed with a package manager. + +### Formatters + +Configure code formatters through the `formatter` option: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "formatter": { + "prettier": { + "disabled": true + }, + "custom-prettier": { + "command": ["npx", "prettier", "--write", "$FILE"], + "environment": { + "NODE_ENV": "development" + }, + "extensions": [".js", ".ts", ".jsx", ".tsx"] + } + } +} +``` + +### Compaction + +Control context compaction behavior through the `compaction` option: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "compaction": { + "auto": true, + "prune": true + } +} +``` + +- `auto`: automatically compact the session when context is full (default: `true`). +- `prune`: remove old tool outputs to save tokens (default: `true`). + +### Watcher + +Configure file watcher ignore patterns through the `watcher` option: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "watcher": { + "ignore": ["node_modules/**", "dist/**", ".git/**"] + } +} +``` + +Patterns follow glob syntax. Use this to exclude noisy directories from file watching. + +### MCP servers + +Configure MCP servers through the `mcp` option: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "mcp": {} +} +``` + +See [MCP servers](/mcp-servers). + +### Plugins + +Plugins extend OpenScience with custom tools, hooks, and integrations. Place plugin files in `.openscience/plugins/` or `~/.config/openscience/plugins/`, or load plugins from npm through the `plugin` option: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "plugin": ["openscience-helicone-session", "@my-org/custom-plugin"] +} +``` + +### Instructions + +Configure instruction files for the model through the `instructions` option: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"] +} +``` + +This takes an array of paths and glob patterns to instruction files. See [Rules](/rules). + +### Billing + +If you use [Atlas](/atlas), pin the spend mode explicitly through the `billing` option: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "billing": { + "llm": "byok", + "compute": "byok" + } +} +``` + +- `llm`: `"managed"` bills LLM calls to your Atlas wallet; `"byok"` uses your own provider keys or subscriptions and is never billed. Unset means auto-detect from the resolved credential. +- `compute`: the same toggle for cloud compute. Defaults to `"byok"`. + +See [Atlas](/atlas#spend-modes). + +### Disabled providers + +Disable providers that are loaded automatically through the `disabled_providers` option. This prevents providers from being loaded even if their credentials are available: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "disabled_providers": ["openai", "gemini"] +} +``` + +When a provider is disabled: + +- It is not loaded even if environment variables are set. +- It is not loaded even if API keys are configured through the `/connect` command. +- The provider's models do not appear in the model selection list. + +### Enabled providers + +Specify an allowlist of providers through the `enabled_providers` option. When set, only the specified providers are enabled and all others are ignored: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "enabled_providers": ["anthropic", "openai"] +} +``` + + +If a provider appears in both `enabled_providers` and `disabled_providers`, `disabled_providers` takes priority. + + +### Experimental + +The `experimental` key contains options that are under active development: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "experimental": {} +} +``` + + +Experimental options are not stable. They may change or be removed without notice. + + +## Variables + +You can use variable substitution in config files to reference environment variables and file contents. + +### Env vars + +Use `{env:VARIABLE_NAME}` to substitute environment variables: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "model": "{env:OPENSCIENCE_MODEL}", + "provider": { + "anthropic": { + "models": {}, + "options": { + "apiKey": "{env:ANTHROPIC_API_KEY}" + } + } + } +} +``` + +If the environment variable is not set, it is replaced with an empty string. + +### Files + +Use `{file:path/to/file}` to substitute the contents of a file: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "instructions": ["./custom-instructions.md"], + "provider": { + "openai": { + "options": { + "apiKey": "{file:~/.secrets/openai-key}" + } + } + } +} +``` + +File paths can be relative to the config file directory, or absolute paths starting with `/` or `~`. + +These are useful for keeping sensitive data like API keys in separate files, including large instruction files without cluttering your config, and sharing common configuration snippets across multiple config files. diff --git a/docs/contributing.mdx b/docs/contributing.mdx new file mode 100644 index 0000000..8898266 --- /dev/null +++ b/docs/contributing.mdx @@ -0,0 +1,72 @@ +--- +title: "Contributing" +description: "How to contribute to OpenScience." +icon: "git-pull-request" +keywords: ["contributing", "development", "bun", "build", "pull requests"] +--- + +OpenScience is open source under the Apache 2.0 license. Contributions are welcome. The full guide lives in [CONTRIBUTING.md](https://github.com/synthetic-sciences/openscience/blob/main/CONTRIBUTING.md) in the repository. + +## What to contribute + +These changes are the most likely to be merged: + +- Bug fixes +- New LSPs and formatters +- Better model performance +- Support for new providers +- Fixes for environment-specific quirks +- Missing standard behavior +- Documentation improvements + +Any UI or core product feature should go through a design discussion with the maintainers before you build it. If you are not sure whether a change would be accepted, ask in an issue or look for issues labeled [`help wanted`](https://github.com/synthetic-sciences/openscience/issues?q=is%3Aissue+state%3Aopen+label%3A%22help+wanted%22) or [`good first issue`](https://github.com/synthetic-sciences/openscience/issues?q=is%3Aissue+state%3Aopen+label%3A%22good+first+issue%22). + +## Repository layout + +The repo is a single Git repository, organized by runtime boundary, with `main` as the default branch: + +| Path | Contents | +| ----------- | --------------------------------------------------------------------- | +| `frontend/` | Workspace (browser UI), docs/share site, and shared UI | +| `backend/` | CLI/server, skills, sessions, and provider integrations | +| `tooling/` | SDK, plugin runtime, repo automation, launcher, utilities, and patches | + +## Development + +You need [Bun](https://bun.sh) 1.3 or newer. Install dependencies and run the CLI from source: + +```bash +bun install +bun dev +``` + +`bun dev` is the local equivalent of the built `openscience` command. It runs against the `backend/cli` directory by default. To run it elsewhere: + +```bash +bun dev # run in a specific directory +bun dev . # run in the repo root +``` + +Common commands work the same in dev and in the built binary: + +```bash +bun dev --help # list commands +bun dev serve # headless API server (port 4096 by default) +bun dev web # start the server and open the workspace +``` + +Typecheck and test: + +```bash +bun run typecheck +bun run --cwd backend/cli test +``` + +## Building a standalone binary + +```bash +./backend/cli/script/build.ts --single +./backend/cli/dist/@synsci/openscience-/bin/openscience +``` + +Replace `` with your platform, for example `darwin-arm64` or `linux-x64`. diff --git a/docs/docs.json b/docs/docs.json new file mode 100644 index 0000000..888fb9b --- /dev/null +++ b/docs/docs.json @@ -0,0 +1,70 @@ +{ + "$schema": "https://mintlify.com/docs.json", + "theme": "mint", + "name": "OpenScience", + "colors": { + "primary": "#0d9488", + "light": "#14b8a6", + "dark": "#0d9488" + }, + "logo": { + "light": "/images/wordmark.svg", + "dark": "/images/wordmark.svg", + "href": "https://openscience.sh" + }, + "favicon": "/favicon.svg", + "appearance": { + "default": "dark" + }, + "navbar": { + "links": [ + { + "type": "github", + "href": "https://github.com/synthetic-sciences/openscience" + } + ] + }, + "navigation": { + "global": { + "anchors": [ + { + "anchor": "GitHub", + "icon": "github", + "href": "https://github.com/synthetic-sciences/openscience" + }, + { + "anchor": "npm", + "icon": "package", + "href": "https://www.npmjs.com/package/@synsci/openscience" + } + ] + }, + "groups": [ + { + "group": "Getting started", + "pages": ["index", "installation"] + }, + { + "group": "Configuration", + "pages": ["config", "models", "providers", "permissions", "rules", "themes"] + }, + { + "group": "Agents and tools", + "pages": ["agents", "tools", "mcp-servers", "skills"] + }, + { + "group": "Platform", + "pages": ["atlas", "share"] + }, + { + "group": "Reference", + "pages": ["cli", "troubleshooting", "contributing"] + } + ] + }, + "footer": { + "socials": { + "github": "https://github.com/synthetic-sciences/openscience" + } + } +} diff --git a/docs/favicon.svg b/docs/favicon.svg new file mode 100644 index 0000000..7410f40 --- /dev/null +++ b/docs/favicon.svg @@ -0,0 +1,17 @@ + + + + + + diff --git a/docs/images/wordmark.svg b/docs/images/wordmark.svg new file mode 100644 index 0000000..9f294c9 --- /dev/null +++ b/docs/images/wordmark.svg @@ -0,0 +1,17 @@ + + + ██████╗ ██████╗ ███████╗███╗ ██╗ + ██╔═══██╗██╔══██╗██╔════╝████╗ ██║ + ██║ ██║██████╔╝█████╗ ██╔██╗ ██║ + ██║ ██║██╔═══╝ ██╔══╝ ██║╚██╗██║ + ╚██████╔╝██║ ███████╗██║ ╚████║ + ╚═════╝ ╚═╝ ╚══════╝╚═╝ ╚═══╝ + ███████╗ ██████╗██╗███████╗███╗ ██╗ ██████╗███████╗ + ██╔════╝██╔════╝██║██╔════╝████╗ ██║██╔════╝██╔════╝ + ███████╗██║ ██║█████╗ ██╔██╗ ██║██║ █████╗ + ╚════██║██║ ██║██╔══╝ ██║╚██╗██║██║ ██╔══╝ + ███████║╚██████╗██║███████╗██║ ╚████║╚██████╗███████╗ + ╚══════╝ ╚═════╝╚═╝╚══════╝╚═╝ ╚═══╝ ╚═════╝╚══════╝ + diff --git a/docs/index.mdx b/docs/index.mdx new file mode 100644 index 0000000..33d54da --- /dev/null +++ b/docs/index.mdx @@ -0,0 +1,137 @@ +--- +title: "Introduction" +description: "Get started with OpenScience, the open-source AI workbench for scientific research." +sidebarTitle: "Introduction" +icon: "rocket" +keywords: ["openscience", "quickstart", "getting started", "ai research agent"] +--- + +OpenScience is an open-source, model-agnostic AI research agent. You give it a goal, and it reads the relevant literature, forms a hypothesis, writes and runs code, runs the experiments, and writes up the result. Running `openscience` opens a workspace in your browser. It also has a [CLI](/cli) for scripting. + +It works with any frontier or open-weight model from Anthropic, OpenAI, Google, and dozens of other providers, using your own API keys. No account is required. + +## Install + +The quickest way to install OpenScience is the install script: + +```bash +curl -fsSL https://openscience.sh/install | bash +``` + +Or install it with npm: + +```bash +npm install -g @synsci/openscience +``` + +Both install the `openscience` command. To install and open the workspace in a single step, run the launcher instead: + +```bash +npx synsci +``` + +See [Installation](/installation) for other package managers, Windows, and platform binaries. + +## Quickstart + + + + Set an API key from any provider (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, and so on) in your shell: + + ```bash + export ANTHROPIC_API_KEY=sk-ant-... + ``` + + You can also add keys from the Credentials panel in the workspace, or with the `/connect` command. Keys stay on your machine and requests go straight to the provider. See [Providers](/providers) for the full list. + + + Navigate to a project and run OpenScience: + + ```bash + cd /path/to/project + openscience + ``` + + This opens the workspace in your browser. Pick a model with the `/models` command. + + + Run the `/init` command in the workspace: + + ```text + /init + ``` + + This analyzes your project and creates an `AGENTS.md` file in the project root. It helps OpenScience understand the project structure and the patterns used. Commit it to Git so your team shares the same context. See [Rules](/rules). + + + Ask it anything. Use the `@` key to fuzzy-search for files in the project: + + ```text + How is authentication handled in @packages/functions/src/api/index.ts + ``` + + + + +If you are new to LLM providers, [Atlas](/atlas) is Synthetic Sciences' optional managed platform with a curated set of tested models billed from a prepaid wallet. Bring-your-own-key usage is free, first-class, and needs no account. + + +## Working with OpenScience + +### Plan first + +OpenScience has a plan mode that turns off its ability to make changes and instead suggests how it will approach the work. Switch to it with the mode selector in the workspace, describe what you want, then iterate on the plan: + +```text +When a user deletes a note, flag it as deleted in the database. +Then create a screen that shows all the recently deleted notes. +``` + +Once you are comfortable with the plan, switch back to the research agent and ask it to make the changes. You can drag and drop images into the workspace to add them to a prompt. + +### Make changes directly + +For straightforward changes, skip the plan and describe the change with enough context: + +```text +We need to add authentication to the /settings route. Take a look at how this is +handled in the /notes route in @packages/functions/src/notes.ts and implement +the same logic in @packages/functions/src/settings.ts +``` + +### Undo and redo + +If a change is not what you wanted, revert it with the `/undo` command: + +```text +/undo +``` + +You can run `/undo` multiple times to step back through changes, and `/redo` to reapply them. + +### Share a session + +Conversations can be [shared with your team](/share): + +```text +/share +``` + +This creates a link to the current conversation and copies it to your clipboard. Conversations are not shared by default. + +## Next steps + + + + Configure OpenScience with the openscience.json config file. + + + Pick a model and set a default. + + + Use the built-in research agents or create your own. + + + Commands, flags, and environment variables. + + diff --git a/docs/installation.mdx b/docs/installation.mdx new file mode 100644 index 0000000..b2798de --- /dev/null +++ b/docs/installation.mdx @@ -0,0 +1,101 @@ +--- +title: "Installation" +description: "Install OpenScience on Linux, macOS, or Windows." +icon: "download" +keywords: ["install", "npm", "curl", "binary", "windows", "upgrade", "uninstall"] +--- + +OpenScience ships as native binaries for Linux, macOS, and Windows. All of the methods below install the `openscience` command. + +## Install script + +On Linux and macOS, the install script downloads the right binary for your platform and adds it to your `PATH`: + +```bash +curl -fsSL https://openscience.sh/install | bash +``` + +To install a specific version: + +```bash +curl -fsSL https://openscience.sh/install | bash -s -- --version 1.0.180 +``` + +Pass `--no-modify-path` if you do not want the script to touch your shell config files. + +## Package managers + + + + ```bash + npm install -g @synsci/openscience + ``` + + + ```bash + bun install -g @synsci/openscience + ``` + + + ```bash + pnpm install -g @synsci/openscience + ``` + + + ```bash + yarn global add @synsci/openscience + ``` + + + +## Launcher + +To install and open the workspace in a single step, run the launcher: + +```bash +npx synsci +``` + +## Windows + +Install with npm: + +```bash +npm install -g @synsci/openscience +``` + +Support for installing OpenScience on Windows using Bun is in progress. + + +Mise (`mise use -g github:synthetic-sciences/openscience`) is a community-maintained install method and is not tested by the OpenScience team. + + +## Binaries + +Platform binaries are attached to each [GitHub release](https://github.com/synthetic-sciences/openscience/releases). Download the archive for your platform, extract it, and put the `openscience` binary on your `PATH`. + +## Upgrade + +OpenScience checks for updates on startup by default. To upgrade manually: + +```bash +openscience upgrade +``` + +To upgrade to a specific version: + +```bash +openscience upgrade v0.1.48 +``` + +You can disable automatic updates with the [`autoupdate` config option](/config#autoupdate). + +## Uninstall + +To remove OpenScience and its data: + +```bash +openscience uninstall +``` + +Pass `--keep-config` to keep configuration files or `--keep-data` to keep session data. Use `--dry-run` to see what would be removed first. See the [CLI reference](/cli#uninstall) for all flags. diff --git a/docs/mcp-servers.mdx b/docs/mcp-servers.mdx new file mode 100644 index 0000000..51cf0ac --- /dev/null +++ b/docs/mcp-servers.mdx @@ -0,0 +1,408 @@ +--- +title: "MCP servers" +description: "Add local and remote MCP tools." +icon: "server" +keywords: ["mcp", "model context protocol", "oauth", "remote servers", "local servers"] +--- + +You can add external tools to OpenScience using the Model Context Protocol (MCP). OpenScience supports both local and remote servers. Once added, MCP tools are automatically available to the LLM alongside built-in tools. + + +Every MCP server adds to the context. Certain servers, like the GitHub MCP server, add a lot of tokens and can easily exceed the context limit. Be selective about which servers you enable. + + +## Enable + +Define MCP servers in your [OpenScience config](/config) under `mcp`. Add each server with a unique name; you can refer to that name when prompting the LLM: + +```jsonc openscience.jsonc +{ + "$schema": "https://openscience.sh/config.json", + "mcp": { + "name-of-mcp-server": { + // ... + "enabled": true, + }, + "name-of-other-mcp-server": { + // ... + }, + }, +} +``` + +Set `enabled` to `false` to temporarily disable a server without removing it from your config. + +You can also add servers interactively with `openscience mcp add`, and list them with `openscience mcp list`. See the [CLI reference](/cli#mcp). + +### Overriding remote defaults + +Organizations can provide default MCP servers via their `.well-known/openscience` endpoint. These servers may be disabled by default, letting users opt in to the ones they need. To enable a server from your organization's remote config, add it to your local config with `enabled: true`: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "mcp": { + "jira": { + "type": "remote", + "url": "https://jira.example.com/mcp", + "enabled": true + } + } +} +``` + +Your local config values override the remote defaults. See [config precedence](/config#locations). + +## Local + +Add local MCP servers by setting `type` to `"local"`: + +```jsonc openscience.jsonc +{ + "$schema": "https://openscience.sh/config.json", + "mcp": { + "my-local-mcp-server": { + "type": "local", + // Or ["bun", "x", "my-mcp-command"] + "command": ["npx", "-y", "my-mcp-command"], + "enabled": true, + "environment": { + "MY_ENV_VAR": "my_env_var_value", + }, + }, + }, +} +``` + +The command is how the local MCP server is started, and `environment` passes environment variables to it. + +For example, here is the test [`@modelcontextprotocol/server-everything`](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) server: + +```jsonc openscience.jsonc +{ + "$schema": "https://openscience.sh/config.json", + "mcp": { + "mcp_everything": { + "type": "local", + "command": ["npx", "-y", "@modelcontextprotocol/server-everything"], + }, + }, +} +``` + +To use it, mention it in your prompt: + +```text +use the mcp_everything tool to add the number 3 and 4 +``` + +### Options + +| Option | Type | Required | Description | +| ------------- | ------- | -------- | ------------------------------------------------------------------------------------ | +| `type` | String | Yes | Type of MCP server connection, must be `"local"`. | +| `command` | Array | Yes | Command and arguments to run the MCP server. | +| `environment` | Object | | Environment variables to set when running the server. | +| `enabled` | Boolean | | Enable or disable the MCP server on startup. | +| `timeout` | Number | | Timeout in ms for fetching tools from the MCP server. Defaults to 5000 (5 seconds). | + +## Remote + +Add remote MCP servers by setting `type` to `"remote"`: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "mcp": { + "my-remote-mcp": { + "type": "remote", + "url": "https://my-mcp-server.com", + "enabled": true, + "headers": { + "Authorization": "Bearer MY_API_KEY" + } + } + } +} +``` + +### Options + +| Option | Type | Required | Description | +| --------- | --------------- | -------- | ------------------------------------------------------------------------------------ | +| `type` | String | Yes | Type of MCP server connection, must be `"remote"`. | +| `url` | String | Yes | URL of the remote MCP server. | +| `enabled` | Boolean | | Enable or disable the MCP server on startup. | +| `headers` | Object | | Headers to send with the request. | +| `oauth` | Object \| false | | OAuth authentication configuration. See [OAuth](#oauth). | +| `timeout` | Number | | Timeout in ms for fetching tools from the MCP server. Defaults to 5000 (5 seconds). | + +## OAuth + +OpenScience automatically handles OAuth authentication for remote MCP servers. When a server requires authentication, OpenScience: + +1. Detects the 401 response and initiates the OAuth flow +2. Uses Dynamic Client Registration (RFC 7591) if the server supports it +3. Stores tokens securely for future requests + +### Automatic + +For most OAuth-enabled MCP servers, no special configuration is needed. Just configure the remote server: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "mcp": { + "my-oauth-server": { + "type": "remote", + "url": "https://mcp.example.com/mcp" + } + } +} +``` + +If the server requires authentication, OpenScience prompts you when you first try to use it. You can also [trigger the flow manually](#authenticating) with `openscience mcp auth `. + +### Pre-registered + +If you have client credentials from the MCP server provider, configure them: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "mcp": { + "my-oauth-server": { + "type": "remote", + "url": "https://mcp.example.com/mcp", + "oauth": { + "clientId": "{env:MY_MCP_CLIENT_ID}", + "clientSecret": "{env:MY_MCP_CLIENT_SECRET}", + "scope": "tools:read tools:execute" + } + } + } +} +``` + +### Authenticating + +Authenticate with a specific MCP server: + +```bash +openscience mcp auth my-oauth-server +``` + +List all MCP servers and their auth status: + +```bash +openscience mcp list +``` + +Remove stored credentials: + +```bash +openscience mcp logout my-oauth-server +``` + +The `mcp auth` command opens your browser for authorization. After you authorize, OpenScience stores the tokens in `~/.local/share/openscience/mcp-auth.json`. + +### Disabling OAuth + +To disable automatic OAuth for a server (for example, servers that use API keys instead), set `oauth` to `false`: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "mcp": { + "my-api-key-server": { + "type": "remote", + "url": "https://mcp.example.com/mcp", + "oauth": false, + "headers": { + "Authorization": "Bearer {env:MY_API_KEY}" + } + } + } +} +``` + +### OAuth options + +| Option | Type | Description | +| -------------- | --------------- | ---------------------------------------------------------------------------------- | +| `oauth` | Object \| false | OAuth config object, or `false` to disable OAuth auto-detection. | +| `clientId` | String | OAuth client ID. If not provided, dynamic client registration is attempted. | +| `clientSecret` | String | OAuth client secret, if required by the authorization server. | +| `scope` | String | OAuth scopes to request during authorization. | + +### Debugging + +If a remote MCP server fails to authenticate: + +```bash +# View auth status for all OAuth-capable servers +openscience mcp auth list + +# Debug connection and OAuth flow for a specific server +openscience mcp debug my-oauth-server +``` + +The `mcp debug` command shows the current auth status, tests HTTP connectivity, and attempts the OAuth discovery flow. + +## Manage + +MCP tools are available alongside built-in tools, so you manage them through the config like any other tool. + +### Global + +Enable or disable them globally: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "mcp": { + "my-mcp-foo": { + "type": "local", + "command": ["bun", "x", "my-mcp-command-foo"] + }, + "my-mcp-bar": { + "type": "local", + "command": ["bun", "x", "my-mcp-command-bar"] + } + }, + "tools": { + "my-mcp*": false + } +} +``` + +Here the glob pattern `my-mcp*` disables all matching MCP tools. + +### Per agent + +If you have a large number of MCP servers, you can disable them globally and enable them only for specific agents: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "mcp": { + "my-mcp": { + "type": "local", + "command": ["bun", "x", "my-mcp-command"], + "enabled": true + } + }, + "tools": { + "my-mcp*": false + }, + "agent": { + "my-agent": { + "tools": { + "my-mcp*": true + } + } + } +} +``` + +### Glob patterns + +- `*` matches zero or more of any character (for example, `"my-mcp*"` matches `my-mcp_search`, `my-mcp_list`, and so on) +- `?` matches exactly one character +- All other characters match literally + + +MCP server tools are registered with the server name as a prefix, so to disable all tools for a server use `"mymcpservername_*": false`. + + +## Examples + +### Sentry + +Add the [Sentry MCP server](https://mcp.sentry.dev) to interact with your Sentry projects and issues: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "mcp": { + "sentry": { + "type": "remote", + "url": "https://mcp.sentry.dev/mcp", + "oauth": {} + } + } +} +``` + +Then authenticate with Sentry: + +```bash +openscience mcp auth sentry +``` + +This opens a browser window to complete the OAuth flow. Once authenticated, you can query issues, projects, and error data: + +```text +Show me the latest unresolved issues in my project. use sentry +``` + +### Context7 + +Add the [Context7 MCP server](https://github.com/upstash/context7) to search through docs: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "mcp": { + "context7": { + "type": "remote", + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +With a free account you can use an API key for higher rate limits: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "mcp": { + "context7": { + "type": "remote", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}" + } + } + } +} +``` + +Add `use context7` to your prompts, or add a rule to your [AGENTS.md](/rules): + +```markdown AGENTS.md +When you need to search docs, use `context7` tools. +``` + +### Grep by Vercel + +Add the [Grep by Vercel](https://grep.app) MCP server to search code on GitHub: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "mcp": { + "gh_grep": { + "type": "remote", + "url": "https://mcp.grep.app" + } + } +} +``` + +Since the server is named `gh_grep`, add `use the gh_grep tool` to your prompts, or add a rule to your [AGENTS.md](/rules): + +```markdown AGENTS.md +If you are unsure how to do something, use `gh_grep` to search code examples from GitHub. +``` diff --git a/docs/models.mdx b/docs/models.mdx new file mode 100644 index 0000000..825727a --- /dev/null +++ b/docs/models.mdx @@ -0,0 +1,185 @@ +--- +title: "Models" +description: "Configure an LLM provider and model." +icon: "cpu" +keywords: ["models", "model selection", "variants", "small model", "default model"] +--- + +OpenScience uses the [AI SDK](https://ai-sdk.dev/) and [Models.dev](https://models.dev) to support 75+ LLM providers, and it supports running local models. + +## Providers + +Most popular providers are preloaded by default. If you have added credentials for a provider through the `/connect` command, they are available when you start OpenScience. + +See [Providers](/providers) for setup guides. + +## Select a model + +Once you have configured your provider, select a model in the workspace: + +```text +/models +``` + +## Recommended models + +New models come out every week, but only a few are good at both generating code and tool calling. These models work well with OpenScience, in no particular order (the list is not exhaustive or necessarily up to date): + +- GPT 5.2 +- GPT 5.1 Codex +- Claude Opus 4.5 +- Claude Sonnet 4.5 +- Minimax M2.1 +- Gemini 3 Pro + +## Set a default + +Set the `model` key in your OpenScience config: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "model": "anthropic/claude-sonnet-4-5" +} +``` + +The full ID is `provider_id/model_id`. For example, if you use [Atlas](/atlas), `synsci/gpt-5-nano` selects GPT 5 Nano through the managed `synsci` provider. + +If you have configured a [custom provider](/providers#custom-provider), the `provider_id` is the key from the `provider` section of your config, and the `model_id` is the key from `provider.models`. + +## Configure models + +You can globally configure a model's options through the config: + +```jsonc openscience.jsonc +{ + "$schema": "https://openscience.sh/config.json", + "provider": { + "openai": { + "models": { + "gpt-5": { + "options": { + "reasoningEffort": "high", + "textVerbosity": "low", + "reasoningSummary": "auto", + "include": ["reasoning.encrypted_content"], + }, + }, + }, + }, + "anthropic": { + "models": { + "claude-sonnet-4-5-20250929": { + "options": { + "thinking": { + "type": "enabled", + "budgetTokens": 16000, + }, + }, + }, + }, + }, + }, +} +``` + +This configures global settings for two built-in models: `gpt-5` when accessed via the `openai` provider, and `claude-sonnet-4-5-20250929` when accessed via the `anthropic` provider. Built-in provider and model names are listed on [Models.dev](https://models.dev). + +You can also configure these options per [agent](/agents#additional-options). Agent config overrides the global options. + +## Variants + +Many models support multiple variants with different configurations. Variants let you configure different settings for the same model without creating duplicate entries. + +### Built-in variants + +OpenScience ships with default variants for popular providers. + +**Anthropic**: + +- `high`: high thinking budget (default) +- `max`: maximum thinking budget + +**OpenAI** (varies by model): + +- `none`: no reasoning +- `minimal`: minimal reasoning effort +- `low`: low reasoning effort +- `medium`: medium reasoning effort +- `high`: high reasoning effort +- `xhigh`: extra high reasoning effort + +**Google**: + +- `low`: lower effort/token budget +- `high`: higher effort/token budget + +This list is not comprehensive; many other providers have built-in defaults too. + +### Custom variants + +You can override existing variants or add your own: + +```jsonc openscience.jsonc +{ + "$schema": "https://openscience.sh/config.json", + "provider": { + "openai": { + "models": { + "gpt-5": { + "variants": { + "thinking": { + "reasoningEffort": "high", + "textVerbosity": "low", + }, + "fast": { + "disabled": true, + }, + }, + }, + }, + }, + }, +} +``` + +Variants also work for models served through the managed `synsci` provider: + +```jsonc openscience.jsonc +{ + "$schema": "https://openscience.sh/config.json", + "provider": { + "synsci": { + "models": { + "gpt-5": { + "variants": { + "high": { + "reasoningEffort": "high", + "textVerbosity": "low", + "reasoningSummary": "auto", + }, + "low": { + "reasoningEffort": "low", + "textVerbosity": "low", + "reasoningSummary": "auto", + }, + }, + }, + }, + }, + }, +} +``` + +### Cycle variants + +Use the `variant_cycle` keybind to switch between variants during a session. + +## Loading models + +When OpenScience starts up, it checks for models in the following priority order: + +1. The `--model` or `-m` command line flag, in the form `provider_id/model_id`. +2. The `model` key in the OpenScience config. +3. The last used model. +4. The first model using an internal priority. diff --git a/docs/permissions.mdx b/docs/permissions.mdx new file mode 100644 index 0000000..9a4a56b --- /dev/null +++ b/docs/permissions.mdx @@ -0,0 +1,223 @@ +--- +title: "Permissions" +description: "Control which actions require approval to run." +icon: "shield" +keywords: ["permissions", "allow", "ask", "deny", "bash", "edit", "external directories"] +--- + +OpenScience uses the `permission` config to decide whether a given action should run automatically, prompt you, or be blocked. + +As of `v1.1.1`, the legacy `tools` boolean config is deprecated and has been merged into `permission`. The old `tools` config is still supported for backwards compatibility. + +## Actions + +Each permission rule resolves to one of: + +- `"allow"`: run without approval +- `"ask"`: prompt for approval +- `"deny"`: block the action + +## Configuration + +You can set permissions globally (with `*`) and override specific tools: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "permission": { + "*": "ask", + "bash": "allow", + "edit": "deny" + } +} +``` + +You can also set all permissions at once: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "permission": "allow" +} +``` + +## Granular rules + +For most permissions, you can use an object to apply different actions based on the tool input: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "permission": { + "bash": { + "*": "ask", + "git *": "allow", + "npm *": "allow", + "rm *": "deny", + "grep *": "allow" + }, + "edit": { + "*": "deny", + "docs/*.mdx": "allow" + } + } +} +``` + +Rules are evaluated by pattern match, with the last matching rule winning. A common pattern is to put the catch-all `"*"` rule first, and more specific rules after it. + +### Wildcards + +Permission patterns use simple wildcard matching: + +- `*` matches zero or more of any character +- `?` matches exactly one character +- All other characters match literally + +### Home directory expansion + +You can use `~` or `$HOME` at the start of a pattern to reference your home directory. This is particularly useful for [`external_directory`](#external-directories) rules. + +- `~/projects/*` expands to `/Users/username/projects/*` +- `$HOME/projects/*` expands to `/Users/username/projects/*` +- `~` expands to `/Users/username` + +### External directories + +Use `external_directory` to allow tool calls that touch paths outside the working directory where OpenScience was started. This applies to any tool that takes a path as input (for example `read`, `edit`, `list`, `glob`, `grep`, and many `bash` commands). + +Home expansion (like `~/...`) only affects how a pattern is written. It does not make an external path part of the current workspace, so paths outside the working directory must still be allowed via `external_directory`. + +For example, this allows access to everything under `~/projects/personal/`: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "permission": { + "external_directory": { + "~/projects/personal/**": "allow" + } + } +} +``` + +Any directory allowed here inherits the same defaults as the current workspace. Since [`read` defaults to `allow`](#defaults), reads are also allowed for entries under `external_directory` unless overridden. Add explicit rules when a tool should be restricted in these paths, such as blocking edits while keeping reads: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "permission": { + "external_directory": { + "~/projects/personal/**": "allow" + }, + "edit": { + "~/projects/personal/**": "deny" + } + } +} +``` + +Keep the list focused on trusted paths, and layer extra allow or deny rules as needed for other tools. + +## Available permissions + +Permissions are keyed by tool name, plus a couple of safety guards: + +- `read`: reading a file (matches the file path) +- `edit`: all file modifications (covers `edit`, `write`, `patch`, `multiedit`) +- `glob`: file globbing (matches the glob pattern) +- `grep`: content search (matches the regex pattern) +- `list`: listing files in a directory (matches the directory path) +- `bash`: running shell commands (matches parsed commands like `git status --porcelain`) +- `task`: launching subagents (matches the subagent type) +- `skill`: loading a skill (matches the skill name) +- `lsp`: running LSP queries (currently non-granular) +- `todoread`, `todowrite`: reading/updating the todo list +- `webfetch`: fetching a URL (matches the URL) +- `websearch`, `codesearch`: web/code search (matches the query) +- `external_directory`: triggered when a tool touches paths outside the project working directory +- `doom_loop`: triggered when the same tool call repeats 3 times with identical input + +## Defaults + +If you do not specify anything, OpenScience starts from permissive defaults: + +- Most permissions default to `"allow"`. +- `doom_loop` and `external_directory` default to `"ask"`. +- `read` is `"allow"`, but `.env` files are denied by default: + +```json openscience.json +{ + "permission": { + "read": { + "*": "allow", + "*.env": "deny", + "*.env.*": "deny", + "*.env.example": "allow" + } + } +} +``` + +## What "ask" does + +When OpenScience prompts for approval, the UI offers three outcomes: + +- `once`: approve just this request +- `always`: approve future requests matching the suggested patterns, for the rest of the current session +- `reject`: deny the request + +The set of patterns that `always` would approve is provided by the tool. For example, bash approvals typically allowlist a safe command prefix like `git status*`. + +## Agents + +You can override permissions per agent. Agent permissions are merged with the global config, and agent rules take precedence: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "permission": { + "bash": { + "*": "ask", + "git *": "allow", + "git commit *": "deny", + "git push *": "deny", + "grep *": "allow" + } + }, + "agent": { + "research": { + "permission": { + "bash": { + "*": "ask", + "git *": "allow", + "git commit *": "ask", + "git push *": "deny", + "grep *": "allow" + } + } + } + } +} +``` + +You can also configure agent permissions in markdown agent definitions: + +```markdown ~/.config/openscience/agents/review.md +--- +description: Code review without edits +mode: subagent +permission: + edit: deny + bash: ask + webfetch: deny +--- + +Only analyze code and suggest changes. +``` + + +Use pattern matching for commands with arguments. `"grep *"` allows `grep pattern file.txt`, while `"grep"` alone would block it. Commands like `git status` work for default behavior but require explicit permission (like `"git status *"`) when arguments are passed. + + +See [Agents](/agents#permissions) for more on per-agent configuration. diff --git a/docs/providers.mdx b/docs/providers.mdx new file mode 100644 index 0000000..c4f8f88 --- /dev/null +++ b/docs/providers.mdx @@ -0,0 +1,406 @@ +--- +title: "Providers" +description: "Use any LLM provider with OpenScience." +icon: "plug" +keywords: ["providers", "anthropic", "openai", "google", "bedrock", "ollama", "byok", "api keys"] +--- + +OpenScience uses the [AI SDK](https://ai-sdk.dev/) and [Models.dev](https://models.dev) to support 75+ LLM providers, plus local models. + +To add a provider: + +1. Add the provider's API key with the `/connect` command in the workspace, or `openscience auth login` in your terminal. +2. Optionally customize the provider in your [OpenScience config](/config). + +### Credentials + +When you add a provider's API key, it is stored locally in `~/.local/share/openscience/auth.json`. Keys never leave your machine; requests go straight to the provider. OpenScience also picks up keys from your environment and from a `.env` file in your project. + +### Base URL + +You can customize the base URL for any provider with the `baseURL` option. This is useful for proxy services or custom endpoints: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "provider": { + "anthropic": { + "options": { + "baseURL": "https://api.anthropic.com/v1" + } + } + } +} +``` + +## Atlas + +[Atlas](/atlas) is Synthetic Sciences' managed platform. It includes a curated set of models that have been tested and verified to work well with OpenScience, served through the managed `synsci` provider and billed from a prepaid wallet. + +1. Sign in from the CLI and approve the sign-in from your browser: + + ```bash + openscience connect login + ``` + +2. On headless or CI machines, create an API key at [app.syntheticsciences.ai](https://app.syntheticsciences.ai/cli) and pass it directly: + + ```bash + openscience connect login --key thk_... + ``` + +3. Run the `/models` command to select one of the curated `synsci/...` models. + +Atlas works like any other provider and is completely optional. Bring-your-own-key usage is free and needs no account. + +## Directory + +Setup guides for common providers. For providers not listed here, the flow is usually the same: create an API key in the provider's console, run `/connect`, search for the provider, paste the key, then pick a model with `/models`. Any OpenAI-compatible API can also be added as a [custom provider](#custom-provider). + +### Anthropic + +1. Run the `/connect` command and select Anthropic. + +2. Select the **Claude Pro/Max** option to authenticate in your browser, or: + - **Create an API Key**: opens your browser, logs you in to Anthropic, and gives you a code to paste into the workspace. + - **Manually enter API Key**: paste an existing key. + +3. All Anthropic models are now available through the `/models` command. + + +Using a Claude Pro/Max subscription in OpenScience is not officially supported by Anthropic. + + +### OpenAI + +1. Run the `/connect` command and select OpenAI. + +2. Select the **ChatGPT Plus/Pro** option to authenticate in your browser, or select **Manually enter API Key** and paste an API key. + +3. All OpenAI models are now available through the `/models` command. + +### Google Vertex AI + +1. Check the models available in your region in the Model Garden in the Google Cloud Console. You need a Google Cloud project with the Vertex AI API enabled. + +2. Set the required environment variables: + + ```bash ~/.bash_profile + export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json + export GOOGLE_CLOUD_PROJECT=your-project-id + export VERTEX_LOCATION=global + ``` + + - `GOOGLE_CLOUD_PROJECT`: your Google Cloud project ID. + - `VERTEX_LOCATION` (optional): the region for Vertex AI (defaults to `global`). + - Authentication: set `GOOGLE_APPLICATION_CREDENTIALS` to a service account JSON key file, or authenticate with `gcloud auth application-default login`. + +3. Run the `/models` command to select a model. + + +The `global` region improves availability and reduces errors at no extra cost. Use regional endpoints (for example `us-central1`) for data residency requirements. + + +### Amazon Bedrock + +1. Request access to the models you want in the Model catalog in the Amazon Bedrock console. + +2. Configure authentication using environment variables: + + ```bash + # Option 1: AWS access keys + AWS_ACCESS_KEY_ID=XXX AWS_SECRET_ACCESS_KEY=YYY openscience + + # Option 2: named AWS profile + AWS_PROFILE=my-profile openscience + + # Option 3: Bedrock bearer token + AWS_BEARER_TOKEN_BEDROCK=XXX openscience + ``` + + Or use the config file (config options take precedence over environment variables): + + ```json openscience.json + { + "$schema": "https://openscience.sh/config.json", + "provider": { + "amazon-bedrock": { + "options": { + "region": "us-east-1", + "profile": "my-aws-profile" + } + } + } + } + ``` + + - `region`: AWS region (defaults to `AWS_REGION` or `us-east-1`). + - `profile`: AWS named profile from `~/.aws/credentials`. + - `endpoint`: custom endpoint URL for VPC endpoints. This is an alias for the generic `baseURL` option; if both are specified, `endpoint` takes precedence. + +3. Run the `/models` command to select a model. + +Authentication precedence for Bedrock: + +1. Bearer token: `AWS_BEARER_TOKEN_BEDROCK` or a token from `/connect`. +2. AWS credential chain: profile, access keys, shared credentials, IAM roles, Web Identity Tokens (EKS IRSA), instance metadata. + + +For custom inference profiles, use the model and provider name in the key and set the `id` property to the ARN so caching works correctly: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "provider": { + "amazon-bedrock": { + "models": { + "anthropic-claude-sonnet-4.5": { + "id": "arn:aws:bedrock:us-east-1:xxx:application-inference-profile/yyy" + } + } + } + } +} +``` + + +### Azure OpenAI + +1. Create an **Azure OpenAI** resource in the [Azure portal](https://portal.azure.com/). You need the resource name (part of your endpoint, `https://RESOURCE_NAME.openai.azure.com/`) and an API key (`KEY 1` or `KEY 2`). + +2. Deploy a model in [Azure AI Foundry](https://ai.azure.com/). The deployment name must match the model name. + +3. Run the `/connect` command, search for **Azure**, and enter your API key. + +4. Set your resource name as an environment variable: + + ```bash ~/.bash_profile + export AZURE_RESOURCE_NAME=XXX + ``` + +5. Run the `/models` command to select your deployed model. + + +If you encounter "I'm sorry, but I cannot assist with that request" errors, try changing the content filter from **DefaultV2** to **Default** in your Azure resource. + + +### GitHub Copilot + +1. Run the `/connect` command and search for GitHub Copilot. + +2. Navigate to [github.com/login/device](https://github.com/login/device) and enter the code shown in the workspace. + +3. Run the `/models` command to select a model. + + +Some models require a Pro+ subscription, and some need to be manually enabled in your GitHub Copilot settings. + + +### OpenRouter + +1. Create an API key in the [OpenRouter dashboard](https://openrouter.ai/settings/keys). + +2. Run the `/connect` command, search for OpenRouter, and enter the key. + +3. Many OpenRouter models are preloaded by default; run `/models` to select one. You can add additional models and customize routing through your config: + + ```json openscience.json + { + "$schema": "https://openscience.sh/config.json", + "provider": { + "openrouter": { + "models": { + "moonshotai/kimi-k2": { + "options": { + "provider": { + "order": ["baseten"], + "allow_fallbacks": false + } + } + } + } + } + } + } + ``` + +### Other API-key providers + +The same create-key, `/connect`, `/models` flow works for 302.AI, Baseten, Cerebras, Cortecs, DeepSeek, Deep Infra, Fireworks AI, Groq, Hugging Face, IO.NET, MiniMax, Moonshot AI, Nebius Token Factory, Ollama Cloud, OVHcloud AI Endpoints, Scaleway, Together AI, Venice AI, Vercel AI Gateway, xAI, Z.AI, ZenMux, and more. Run `/connect` and search for the provider by name. + +## Local models + +Run local models through any OpenAI-compatible server by defining a custom provider in your config. + + + +```json Ollama +{ + "$schema": "https://openscience.sh/config.json", + "provider": { + "ollama": { + "npm": "@ai-sdk/openai-compatible", + "name": "Ollama (local)", + "options": { + "baseURL": "http://localhost:11434/v1" + }, + "models": { + "llama2": { + "name": "Llama 2" + } + } + } + } +} +``` + +```json LM Studio +{ + "$schema": "https://openscience.sh/config.json", + "provider": { + "lmstudio": { + "npm": "@ai-sdk/openai-compatible", + "name": "LM Studio (local)", + "options": { + "baseURL": "http://127.0.0.1:1234/v1" + }, + "models": { + "google/gemma-3n-e4b": { + "name": "Gemma 3n-e4b (local)" + } + } + } + } +} +``` + +```json llama.cpp +{ + "$schema": "https://openscience.sh/config.json", + "provider": { + "llama.cpp": { + "npm": "@ai-sdk/openai-compatible", + "name": "llama-server (local)", + "options": { + "baseURL": "http://127.0.0.1:8080/v1" + }, + "models": { + "qwen3-coder:a3b": { + "name": "Qwen3-Coder: a3b-30b (local)", + "limit": { + "context": 128000, + "output": 65536 + } + } + } + } + } +} +``` + + + +In these examples: + +- The provider key (`ollama`, `lmstudio`, `llama.cpp`) is a custom provider ID. It can be any string. +- `npm` specifies the package for the provider. `@ai-sdk/openai-compatible` works for any OpenAI-compatible API. +- `name` is the display name in the UI. +- `options.baseURL` is the endpoint for the local server. +- `models` maps model IDs to their configurations. + + +If tool calls are not working with Ollama, try increasing `num_ctx`. Start around 16k to 32k. + + +## Custom provider + +To add any OpenAI-compatible provider that is not listed in the `/connect` command: + +1. Run the `/connect` command and scroll down to **Other**. + +2. Enter a unique ID for the provider. Choose a memorable ID; you will use it in your config file. + +3. Enter your API key for the provider. + +4. Create or update `openscience.json` in your project directory: + + ```json openscience.json + { + "$schema": "https://openscience.sh/config.json", + "provider": { + "myprovider": { + "npm": "@ai-sdk/openai-compatible", + "name": "My Provider Display Name", + "options": { + "baseURL": "https://api.myprovider.com/v1" + }, + "models": { + "my-model-name": { + "name": "My Model Display Name" + } + } + } + } + } + ``` + +5. Run the `/models` command; your custom provider and models appear in the selection list. + +Configuration options: + +- `npm`: AI SDK package to use. `@ai-sdk/openai-compatible` for OpenAI-compatible providers. +- `name`: display name in the UI. +- `models`: available models. +- `options.baseURL`: API endpoint URL. +- `options.apiKey`: optionally set the API key, if not using `/connect`. +- `options.headers`: optionally set custom headers. + +Here is an example setting the `apiKey`, `headers`, and model `limit` options: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "provider": { + "myprovider": { + "npm": "@ai-sdk/openai-compatible", + "name": "My Provider Display Name", + "options": { + "baseURL": "https://api.myprovider.com/v1", + "apiKey": "{env:MYPROVIDER_API_KEY}", + "headers": { + "Authorization": "Bearer custom-token" + } + }, + "models": { + "my-model-name": { + "name": "My Model Display Name", + "limit": { + "context": 200000, + "output": 65536 + } + } + } + } + } +} +``` + +- `apiKey`: set using the [`{env:...}` variable syntax](/config#env-vars). +- `headers`: custom headers sent with each request. +- `limit.context`: maximum input tokens the model accepts. +- `limit.output`: maximum tokens the model can generate. + +The `limit` fields let OpenScience track how much context you have left. Standard providers pull these from Models.dev automatically. + +## Troubleshooting + +If a provider is not working: + +1. **Check the auth setup.** Run `openscience auth list` to see if credentials for the provider are stored. This does not apply to providers like Amazon Bedrock that rely on environment variables. + +2. **For custom providers**, check that: + - The provider ID used in the `/connect` command matches the ID in your config. + - The right npm package is used. For example, `@ai-sdk/cerebras` for Cerebras, and `@ai-sdk/openai-compatible` for other OpenAI-compatible providers. + - The correct API endpoint is set in `options.baseURL`. + +See [Troubleshooting](/troubleshooting) for more. diff --git a/docs/rules.mdx b/docs/rules.mdx new file mode 100644 index 0000000..f9e7fc1 --- /dev/null +++ b/docs/rules.mdx @@ -0,0 +1,166 @@ +--- +title: "Rules" +description: "Set custom instructions for OpenScience with AGENTS.md." +icon: "list-checks" +keywords: ["rules", "AGENTS.md", "CLAUDE.md", "instructions", "custom instructions"] +--- + +You can provide custom instructions to OpenScience by creating an `AGENTS.md` file. It contains instructions that are included in the LLM's context to customize its behavior for your project. + +## Initialize + +To create a new `AGENTS.md` file, run the `/init` command in the workspace: + +```text +/init +``` + +This scans your project to understand what it is about and generates an `AGENTS.md` file. If you have an existing `AGENTS.md`, it adds to it. + + +Commit your project's `AGENTS.md` file to Git so your team shares the same context. + + +## Example + +You can also create the file manually: + +```markdown AGENTS.md +# SST v3 Monorepo Project + +This is an SST v3 monorepo with TypeScript. The project uses bun workspaces for package management. + +## Project Structure + +- `packages/` - Contains all workspace packages (functions, core, web, etc.) +- `infra/` - Infrastructure definitions split by service (storage.ts, api.ts, web.ts) +- `sst.config.ts` - Main SST configuration with dynamic imports + +## Code Standards + +- Use TypeScript with strict mode enabled +- Shared code goes in `packages/core/` with proper exports configuration +- Functions go in `packages/functions/` +- Infrastructure should be split into logical files in `infra/` + +## Monorepo Conventions + +- Import shared modules using workspace names: `@my-app/core/example` +``` + +## Locations + +OpenScience reads `AGENTS.md` from multiple locations, each used for a different purpose. + +### Project + +Place an `AGENTS.md` in your project root for project-specific rules. These only apply when you are working in this directory or its subdirectories. + +### Global + +You can also have global rules in `~/.config/openscience/AGENTS.md`. This applies across all OpenScience sessions. + +Since this is not committed to Git or shared with your team, use it for personal rules that the LLM should follow. + +### Claude Code compatibility + +For users migrating from Claude Code, OpenScience supports Claude Code's file conventions as fallbacks: + +- Project rules: `CLAUDE.md` in your project directory (used if no `AGENTS.md` exists) +- Global rules: `~/.claude/CLAUDE.md` (used if no `~/.config/openscience/AGENTS.md` exists) +- Skills: `~/.claude/skills/`, see [Skills](/skills) + +To disable Claude Code compatibility, set one of these environment variables: + +```bash +export OPENSCIENCE_DISABLE_CLAUDE_CODE=1 # Disable all .claude support +export OPENSCIENCE_DISABLE_CLAUDE_CODE_PROMPT=1 # Disable only ~/.claude/CLAUDE.md +export OPENSCIENCE_DISABLE_CLAUDE_CODE_SKILLS=1 # Disable only .claude/skills +``` + +## Precedence + +When OpenScience starts, it looks for rule files in this order: + +1. Local files, by traversing up from the current directory (`AGENTS.md`, `CLAUDE.md`) +2. Global file at `~/.config/openscience/AGENTS.md` +3. Claude Code file at `~/.claude/CLAUDE.md` (unless disabled) + +The first matching file wins in each category. If you have both `AGENTS.md` and `CLAUDE.md`, only `AGENTS.md` is used. Similarly, `~/.config/openscience/AGENTS.md` takes precedence over `~/.claude/CLAUDE.md`. + +## Custom instructions + +You can specify custom instruction files in your `openscience.json` or the global `~/.config/openscience/openscience.json`. This lets you and your team reuse existing rules rather than duplicating them into `AGENTS.md`: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"] +} +``` + +You can also use remote URLs to load instructions from the web: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "instructions": ["https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"] +} +``` + +Remote instructions are fetched with a 5 second timeout. All instruction files are combined with your `AGENTS.md` files. + +## Referencing external files + +OpenScience does not automatically parse file references in `AGENTS.md`, but you can get similar behavior in two ways. + +### Using openscience.json + +The recommended approach is the `instructions` field in `openscience.json`: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "instructions": ["docs/development-standards.md", "test/testing-guidelines.md", "packages/*/AGENTS.md"] +} +``` + +### Manual instructions in AGENTS.md + +You can teach OpenScience to read external files by providing explicit instructions in your `AGENTS.md`: + +```markdown AGENTS.md +# TypeScript Project Rules + +## External File Loading + +CRITICAL: When you encounter a file reference (e.g., @rules/general.md), use your Read tool to load it on a need-to-know basis. They're relevant to the SPECIFIC task at hand. + +Instructions: + +- Do NOT preemptively load all references - use lazy loading based on actual need +- When loaded, treat content as mandatory instructions that override defaults +- Follow references recursively when needed + +## Development Guidelines + +For TypeScript code style and best practices: @docs/typescript-guidelines.md +For React component architecture and hooks patterns: @docs/react-patterns.md +For REST API design and error handling: @docs/api-standards.md +For testing strategies and coverage requirements: @test/testing-guidelines.md + +## General Guidelines + +Read the following file immediately as it's relevant to all workflows: @rules/general-guidelines.md. +``` + +This approach lets you: + +- Create modular, reusable rule files +- Share rules across projects via symlinks or Git submodules +- Keep `AGENTS.md` concise while referencing detailed guidelines +- Ensure OpenScience loads files only when needed for the specific task + + +For monorepos or projects with shared standards, using `openscience.json` with glob patterns (like `packages/*/AGENTS.md`) is more maintainable than manual instructions. + diff --git a/docs/share.mdx b/docs/share.mdx new file mode 100644 index 0000000..51890b2 --- /dev/null +++ b/docs/share.mdx @@ -0,0 +1,97 @@ +--- +title: "Share" +description: "Share your OpenScience conversations." +icon: "share-2" +keywords: ["share", "unshare", "session links", "privacy"] +--- + +The share feature creates public links to your OpenScience conversations, so you can collaborate with teammates or get help from others. + + +Shared conversations are publicly accessible to anyone with the link. + + +## How it works + +When you share a conversation, OpenScience: + +1. Creates a unique public URL for your session +2. Syncs your conversation history to the share servers +3. Makes the conversation accessible at a shareable link: `syntheticsciences.ai/s/` + +## Sharing modes + +OpenScience supports three sharing modes that control how conversations are shared. + +### Manual (default) + +Sessions are not shared automatically, but you can share them with the `/share` command: + +```text +/share +``` + +This generates a unique URL and copies it to your clipboard. + +To explicitly set manual mode in your [config](/config): + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "share": "manual" +} +``` + +### Auto-share + +Enable automatic sharing for all new conversations: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "share": "auto" +} +``` + +With auto-share enabled, every new conversation is shared and a link is generated. + +### Disabled + +Disable sharing entirely: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "share": "disabled" +} +``` + +To enforce this across your team for a given project, add it to the `openscience.json` in your project and check it into Git. + +## Un-sharing + +To stop sharing a conversation and remove it from public access: + +```text +/unshare +``` + +This removes the share link and deletes the data related to the conversation. + +## Privacy + +### Data retention + +Shared conversations remain accessible until you explicitly unshare them. This includes: + +- Full conversation history +- All messages and responses +- Session metadata + +### Recommendations + +- Only share conversations that do not contain sensitive information. +- Review conversation content before sharing. +- Unshare conversations when collaboration is complete. +- Avoid sharing conversations with proprietary code or confidential data. +- For sensitive projects, disable sharing entirely. diff --git a/docs/skills.mdx b/docs/skills.mdx new file mode 100644 index 0000000..85ebf9e --- /dev/null +++ b/docs/skills.mdx @@ -0,0 +1,194 @@ +--- +title: "Skills" +description: "Define reusable behavior with SKILL.md files." +icon: "book-open" +keywords: ["skills", "SKILL.md", "agent skills", "reusable instructions"] +--- + +Agent skills let OpenScience discover reusable instructions from your repo or home directory. Skills are loaded on demand via the native `skill` tool: agents see the available skills and load the full content when needed. + +## Place files + +Create one folder per skill name and put a `SKILL.md` inside it. OpenScience searches these locations: + +- Project config: `.openscience/skills//SKILL.md` +- Global config: `~/.config/openscience/skills//SKILL.md` +- Project Claude-compatible: `.claude/skills//SKILL.md` +- Global Claude-compatible: `~/.claude/skills//SKILL.md` + +## Discovery + +For project-local paths, OpenScience walks up from your current working directory until it reaches the Git worktree. It loads any matching `skills/*/SKILL.md` in `.openscience/` and any matching `.claude/skills/*/SKILL.md` along the way. + +Global definitions are also loaded from `~/.config/openscience/skills/*/SKILL.md` and `~/.claude/skills/*/SKILL.md`. + +## Frontmatter + +Each `SKILL.md` must start with YAML frontmatter. Only these fields are recognized: + +- `name` (required) +- `description` (required) +- `license` (optional) +- `compatibility` (optional) +- `metadata` (optional, string-to-string map) + +Unknown frontmatter fields are ignored. + +### Name rules + +`name` must: + +- Be 1-64 characters +- Be lowercase alphanumeric with single hyphen separators +- Not start or end with `-` +- Not contain consecutive `--` +- Match the directory name that contains `SKILL.md` + +Equivalent regex: + +```text +^[a-z0-9]+(-[a-z0-9]+)*$ +``` + +### Description rules + +`description` must be 1-1024 characters. Keep it specific enough for the agent to choose correctly. + +## Example + +Create `.openscience/skills/git-release/SKILL.md`: + +```markdown SKILL.md +--- +name: git-release +description: Create consistent releases and changelogs +license: Apache-2.0 +compatibility: openscience +metadata: + audience: maintainers + workflow: github +--- + +## What I do + +- Draft release notes from merged PRs +- Propose a version bump +- Provide a copy-pasteable `gh release create` command + +## When to use me + +Use this when you are preparing a tagged release. +Ask clarifying questions if the target versioning scheme is unclear. +``` + +## Tool description + +OpenScience lists available skills in the `skill` tool description. Each entry includes the skill name and description: + +```xml + + + git-release + Create consistent releases and changelogs + + +``` + +The agent loads a skill by calling the tool: + +```text +skill({ name: "git-release" }) +``` + +## Permissions + +Control which skills agents can access using pattern-based [permissions](/permissions): + +```json openscience.json +{ + "permission": { + "skill": { + "*": "allow", + "pr-review": "allow", + "internal-*": "deny", + "experimental-*": "ask" + } + } +} +``` + +| Permission | Behavior | +| ---------- | ------------------------------------------ | +| `allow` | Skill loads immediately | +| `deny` | Skill hidden from agent, access rejected | +| `ask` | User prompted for approval before loading | + +Patterns support wildcards: `internal-*` matches `internal-docs`, `internal-tools`, and so on. + +### Per agent + +Give specific agents different permissions than the global defaults. + +For custom agents, in the agent frontmatter: + +```yaml +--- +permission: + skill: + "documents-*": "allow" +--- +``` + +For built-in agents, in `openscience.json`: + +```json openscience.json +{ + "agent": { + "plan": { + "permission": { + "skill": { + "internal-*": "allow" + } + } + } + } +} +``` + +### Disable the skill tool + +Completely disable skills for agents that should not use them. + +For custom agents: + +```yaml +--- +tools: + skill: false +--- +``` + +For built-in agents: + +```json openscience.json +{ + "agent": { + "plan": { + "tools": { + "skill": false + } + } + } +} +``` + +When disabled, the `` section is omitted entirely. + +## Troubleshooting + +If a skill does not show up: + +1. Verify `SKILL.md` is spelled in all caps +2. Check that the frontmatter includes `name` and `description` +3. Ensure skill names are unique across all locations +4. Check permissions, since skills with `deny` are hidden from agents diff --git a/docs/themes.mdx b/docs/themes.mdx new file mode 100644 index 0000000..da881ed --- /dev/null +++ b/docs/themes.mdx @@ -0,0 +1,172 @@ +--- +title: "Themes" +description: "Select a built-in theme or define your own." +icon: "palette" +keywords: ["themes", "custom themes", "colors", "appearance"] +--- + +You can select from several built-in themes, use a theme that follows your system's light or dark appearance, or define your own custom theme. + +By default, OpenScience uses its own `openscience` theme. + +## Built-in themes + +| Name | Description | +| ---------------------- | ----------------------------------------------------------------------------- | +| `system` | Follows your system's light or dark appearance | +| `tokyonight` | Based on the [Tokyonight](https://github.com/folke/tokyonight.nvim) theme | +| `everforest` | Based on the [Everforest](https://github.com/sainnhe/everforest) theme | +| `ayu` | Based on the [Ayu](https://github.com/ayu-theme) dark theme | +| `catppuccin` | Based on the [Catppuccin](https://github.com/catppuccin) theme | +| `catppuccin-macchiato` | Based on the [Catppuccin](https://github.com/catppuccin) theme | +| `gruvbox` | Based on the [Gruvbox](https://github.com/morhetz/gruvbox) theme | +| `kanagawa` | Based on the [Kanagawa](https://github.com/rebelot/kanagawa.nvim) theme | +| `nord` | Based on the [Nord](https://github.com/nordtheme/nord) theme | +| `matrix` | Hacker-style green on black theme | +| `one-dark` | Based on the [Atom One](https://github.com/Th3Whit3Wolf/one-nvim) Dark theme | + +More themes are added regularly. + +## System theme + +The `system` theme follows your operating system's light or dark appearance instead of using fixed colors. It picks a gray scale that keeps good contrast against the workspace background, and it uses `none` for text and background so the workspace keeps its default look. + +Use it if you want OpenScience to match your system appearance and stay consistent with your other applications. + +## Using a theme + +Select a theme with the `/theme` command in the workspace, or set it in your [config](/config): + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "theme": "tokyonight" +} +``` + +## Custom themes + +OpenScience supports a JSON-based theme system. + +### Hierarchy + +Themes are loaded from multiple directories in the following order, where later directories override earlier ones: + +1. Built-in themes: embedded in the binary +2. User config directory: `~/.config/openscience/themes/*.json` or `$XDG_CONFIG_HOME/openscience/themes/*.json` +3. Project root directory: `/.openscience/themes/*.json` +4. Current working directory: `./.openscience/themes/*.json` + +If multiple directories contain a theme with the same name, the theme from the higher-priority directory is used. + +### Creating a theme + +Create a JSON file in one of the theme directories. + +For user-wide themes: + +```bash +mkdir -p ~/.config/openscience/themes +vim ~/.config/openscience/themes/my-theme.json +``` + +For project-specific themes: + +```bash +mkdir -p .openscience/themes +vim .openscience/themes/my-theme.json +``` + +### JSON format + +Themes support: + +- Hex colors: `"#ffffff"` +- ANSI colors: `3` (0-255) +- Color references: `"primary"` or custom definitions from `defs` +- Dark/light variants: `{"dark": "#000", "light": "#fff"}` +- No color: `"none"` uses the default color or transparent + +The `defs` section is optional and defines reusable colors that can be referenced in the theme. + +The special value `"none"` can be used for any color to inherit the default color or stay transparent. This is useful for themes that follow the surrounding appearance: + +- `"text": "none"` uses the default foreground color +- `"background": "none"` uses the default background color + +### Example + +```json my-theme.json +{ + "$schema": "https://openscience.sh/theme.json", + "defs": { + "nord0": "#2E3440", + "nord1": "#3B4252", + "nord2": "#434C5E", + "nord3": "#4C566A", + "nord4": "#D8DEE9", + "nord6": "#ECEFF4", + "nord7": "#8FBCBB", + "nord8": "#88C0D0", + "nord9": "#81A1C1", + "nord10": "#5E81AC", + "nord11": "#BF616A", + "nord12": "#D08770", + "nord13": "#EBCB8B", + "nord14": "#A3BE8C", + "nord15": "#B48EAD" + }, + "theme": { + "primary": { "dark": "nord8", "light": "nord10" }, + "secondary": { "dark": "nord9", "light": "nord9" }, + "accent": { "dark": "nord7", "light": "nord7" }, + "error": { "dark": "nord11", "light": "nord11" }, + "warning": { "dark": "nord12", "light": "nord12" }, + "success": { "dark": "nord14", "light": "nord14" }, + "info": { "dark": "nord8", "light": "nord10" }, + "text": { "dark": "nord4", "light": "nord0" }, + "textMuted": { "dark": "nord3", "light": "nord1" }, + "background": { "dark": "nord0", "light": "nord6" }, + "backgroundPanel": { "dark": "nord1", "light": "nord4" }, + "backgroundElement": { "dark": "nord1", "light": "nord4" }, + "border": { "dark": "nord2", "light": "nord3" }, + "borderActive": { "dark": "nord3", "light": "nord2" }, + "borderSubtle": { "dark": "nord2", "light": "nord3" }, + "diffAdded": { "dark": "nord14", "light": "nord14" }, + "diffRemoved": { "dark": "nord11", "light": "nord11" }, + "diffContext": { "dark": "nord3", "light": "nord3" }, + "diffHunkHeader": { "dark": "nord3", "light": "nord3" }, + "diffHighlightAdded": { "dark": "nord14", "light": "nord14" }, + "diffHighlightRemoved": { "dark": "nord11", "light": "nord11" }, + "diffAddedBg": { "dark": "#3B4252", "light": "#E5E9F0" }, + "diffRemovedBg": { "dark": "#3B4252", "light": "#E5E9F0" }, + "diffContextBg": { "dark": "nord1", "light": "nord4" }, + "diffLineNumber": { "dark": "nord2", "light": "nord4" }, + "diffAddedLineNumberBg": { "dark": "#3B4252", "light": "#E5E9F0" }, + "diffRemovedLineNumberBg": { "dark": "#3B4252", "light": "#E5E9F0" }, + "markdownText": { "dark": "nord4", "light": "nord0" }, + "markdownHeading": { "dark": "nord8", "light": "nord10" }, + "markdownLink": { "dark": "nord9", "light": "nord9" }, + "markdownLinkText": { "dark": "nord7", "light": "nord7" }, + "markdownCode": { "dark": "nord14", "light": "nord14" }, + "markdownBlockQuote": { "dark": "nord3", "light": "nord3" }, + "markdownEmph": { "dark": "nord12", "light": "nord12" }, + "markdownStrong": { "dark": "nord13", "light": "nord13" }, + "markdownHorizontalRule": { "dark": "nord3", "light": "nord3" }, + "markdownListItem": { "dark": "nord8", "light": "nord10" }, + "markdownListEnumeration": { "dark": "nord7", "light": "nord7" }, + "markdownImage": { "dark": "nord9", "light": "nord9" }, + "markdownImageText": { "dark": "nord7", "light": "nord7" }, + "markdownCodeBlock": { "dark": "nord4", "light": "nord0" }, + "syntaxComment": { "dark": "nord3", "light": "nord3" }, + "syntaxKeyword": { "dark": "nord9", "light": "nord9" }, + "syntaxFunction": { "dark": "nord8", "light": "nord8" }, + "syntaxVariable": { "dark": "nord7", "light": "nord7" }, + "syntaxString": { "dark": "nord14", "light": "nord14" }, + "syntaxNumber": { "dark": "nord15", "light": "nord15" }, + "syntaxType": { "dark": "nord7", "light": "nord7" }, + "syntaxOperator": { "dark": "nord9", "light": "nord9" }, + "syntaxPunctuation": { "dark": "nord4", "light": "nord0" } + } +} +``` diff --git a/docs/tools.mdx b/docs/tools.mdx new file mode 100644 index 0000000..193ffa7 --- /dev/null +++ b/docs/tools.mdx @@ -0,0 +1,128 @@ +--- +title: "Tools" +description: "Manage the tools the LLM can use." +icon: "wrench" +keywords: ["tools", "bash", "edit", "read", "grep", "glob", "webfetch", "skill"] +--- + +Tools let the LLM perform actions in your project. OpenScience comes with a set of built-in tools, and you can extend it with custom tools or [MCP servers](/mcp-servers). + +By default, all tools are enabled and do not need permission to run. You control tool behavior through [permissions](/permissions): + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "permission": { + "edit": "deny", + "bash": "ask", + "webfetch": "allow" + } +} +``` + +You can use wildcards to control multiple tools at once, for example to require approval for all tools from an MCP server: + +```json openscience.json +{ + "$schema": "https://openscience.sh/config.json", + "permission": { + "mymcp_*": "ask" + } +} +``` + +## Built-in tools + +### bash + +Execute shell commands in your project environment. The `bash` permission matches parsed commands, so you can write granular rules like `"git *": "allow"`. + +### edit + +Modify existing files using exact string replacements. This is the primary way the LLM modifies code. + +### write + +Create new files or overwrite existing ones. + + +The `write` tool is controlled by the `edit` permission, which covers all file modifications (`edit`, `write`, `patch`, `multiedit`). + + +### patch + +Apply patch files to your codebase. Also controlled by the `edit` permission. + +### read + +Read file contents. Supports reading specific line ranges for large files. `read` defaults to `allow`, but `.env` files are denied by default; see [permission defaults](/permissions#defaults). + +### grep + +Search file contents using regular expressions. Supports full regex syntax and file pattern filtering. + +### glob + +Find files by pattern matching, like `**/*.js` or `src/**/*.ts`. Returns matching file paths sorted by modification time. + +### list + +List files and directories in a given path. Accepts glob patterns to filter results. + +### lsp (experimental) + +Interact with your configured LSP servers for code intelligence: definitions, references, hover info, and call hierarchy. Supported operations include `goToDefinition`, `findReferences`, `hover`, `documentSymbol`, `workspaceSymbol`, `goToImplementation`, `prepareCallHierarchy`, `incomingCalls`, and `outgoingCalls`. + + +This tool is only available when `OPENSCIENCE_EXPERIMENTAL_LSP_TOOL=true` (or `OPENSCIENCE_EXPERIMENTAL=true`). + + +### skill + +Load a [skill](/skills) (a `SKILL.md` file) and return its content into the conversation. The `skill` permission matches the skill name. + +### todowrite and todoread + +Create, update, and read task lists that track progress during complex, multi-step operations. + + +The todo tools are disabled for subagents by default, but you can enable them per agent. See [agent permissions](/agents#permissions). + + +### webfetch + +Fetch and read web pages. Useful for looking up documentation or researching online resources. The `webfetch` permission matches the URL. + +### question + +Ask you questions during execution. Useful for: + +- Gathering preferences or requirements +- Clarifying ambiguous instructions +- Getting decisions on implementation choices + +Each question includes a header, the question text, and a list of options. You can select from the options or type a custom answer. When there are multiple questions, you can navigate between them before submitting all answers. + +## Custom tools + +Custom tools let you define your own functions that the LLM can call. Place tool files in `.openscience/tools/` or `~/.config/openscience/tools/`. + +## MCP servers + +MCP (Model Context Protocol) servers integrate external tools and services, including database access, API integrations, and third-party services. See [MCP servers](/mcp-servers). + +## Internals + +Internally, tools like `grep`, `glob`, and `list` use [ripgrep](https://github.com/BurntSushi/ripgrep). By default, ripgrep respects `.gitignore` patterns, so files and directories listed in your `.gitignore` are excluded from searches and listings. + +### Ignore patterns + +To include files that would normally be ignored, create a `.ignore` file in your project root: + +```text .ignore +!node_modules/ +!dist/ +!build/ +``` + +This example allows ripgrep to search within `node_modules/`, `dist/`, and `build/` even if they are listed in `.gitignore`. diff --git a/docs/troubleshooting.mdx b/docs/troubleshooting.mdx new file mode 100644 index 0000000..034ab2e --- /dev/null +++ b/docs/troubleshooting.mdx @@ -0,0 +1,134 @@ +--- +title: "Troubleshooting" +description: "Common issues and how to resolve them." +icon: "life-buoy" +keywords: ["troubleshooting", "logs", "storage", "errors", "provider errors"] +--- + +To debug issues with OpenScience, start by checking the logs and the local data it stores on disk. + +## Logs + +Log files are written to: + +- **macOS/Linux**: `~/.local/share/openscience/log/` +- **Windows**: press `WIN+R` and paste `%USERPROFILE%\.local\share\openscience\log` + +Log files are named with timestamps (for example, `2025-01-09T123456.log`) and the most recent 10 log files are kept. + +Set the log level with the `--log-level` flag for more detailed debug information: + +```bash +openscience --log-level DEBUG +``` + +## Storage + +OpenScience stores session data and other application data on disk at: + +- **macOS/Linux**: `~/.local/share/openscience/` +- **Windows**: press `WIN+R` and paste `%USERPROFILE%\.local\share\openscience` + +This directory contains: + +- `auth.json`: authentication data like API keys and OAuth tokens +- `log/`: application logs +- `project/`: project-specific data like session and message data + - If the project is within a Git repo, it is stored in `.//storage/` + - If it is not a Git repo, it is stored in `./global/storage/` + +## Getting help + +Report bugs or request features through the GitHub repository: + +[github.com/synthetic-sciences/openscience/issues](https://github.com/synthetic-sciences/openscience/issues) + +Before creating a new issue, search existing issues to see if your problem has already been reported. + +## Common issues + +### OpenScience won't start + +1. Check the logs for error messages +2. Try running with `--print-logs` to print logs to the console +3. Ensure you have the latest version with `openscience upgrade` + +### Authentication issues + +1. Try re-authenticating with the `/connect` command in the workspace +2. Check that your API keys are valid +3. Ensure your network allows connections to the provider's API + +### Model not available + +1. Check that you have authenticated with the provider +2. Verify the model name in your config is correct +3. Some models may require specific access or subscriptions + +If you encounter `ProviderModelNotFoundError`, you are most likely referencing a model incorrectly. Models are referenced as `/`: + +- `openai/gpt-4.1` +- `openrouter/google/gemini-2.5-flash` +- `synsci/gpt-5-nano` + +To see which models you have access to, run `openscience models`. + +### ProviderInitError + +A `ProviderInitError` usually means an invalid or corrupted configuration. + +1. Verify your provider is set up correctly by following the [providers guide](/providers) +2. If the issue persists, try clearing your stored configuration: + + ```bash + rm -rf ~/.local/share/openscience + ``` + + On Windows, press `WIN+R` and delete `%USERPROFILE%\.local\share\openscience`. + +3. Re-authenticate with your provider using the `/connect` command in the workspace. + +### AI_APICallError and provider package issues + +API call errors can be caused by outdated provider packages. OpenScience dynamically installs provider packages (OpenAI, Anthropic, Google, and so on) as needed and caches them locally. + +1. Clear the provider package cache: + + ```bash + rm -rf ~/.cache/openscience + ``` + + On Windows, press `WIN+R` and delete `%USERPROFILE%\.cache\openscience`. + +2. Restart OpenScience to reinstall the latest provider packages. + +This forces OpenScience to download the most recent provider packages, which often resolves compatibility issues with model parameters and API changes. + +### Copy/paste not working on Linux + +Linux users need one of the following clipboard utilities installed. + +For X11 systems: + +```bash +apt install -y xclip +# or +apt install -y xsel +``` + +For Wayland systems: + +```bash +apt install -y wl-clipboard +``` + +For headless environments: + +```bash +apt install -y xvfb +# and run: +Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 & +export DISPLAY=:99.0 +``` + +OpenScience detects Wayland and prefers `wl-clipboard`, otherwise it tries clipboard tools in order: `xclip`, then `xsel`.