# Configuration
This document covers target-repo bootstrap, generated files, and the runtime
configuration that `opensymphony run` expects.
## Bootstrap
Use `opensymphony init` from the target repository root:
```bash
cd /path/to/target-repo
opensymphony init
```
`opensymphony init` is the primary setup path for existing repositories. It:
- fetches the current starter files from the template repo's raw GitHub URLs
- copies missing files into the target repo
- merges an existing `AGENTS.md`
- prompts before overwriting other conflicting files
- fills the `WORKFLOW.md` clone hook from `git remote` when possible
- offers to fill the Linear project slug/key in `WORKFLOW.md`
- creates or updates `.gitignore` so local OpenSymphony runtime state stays untracked
- can optionally scaffold OpenHands AI PR review
- can configure the GitHub Actions variables, label, and optional review secret
automatically when `gh` is installed and can access the repository
For repositories that are already initialized, `opensymphony update` is the
maintenance path for template-owned skills:
```bash
cd /path/to/target-repo
opensymphony update
```
The command first checks whether the installed CLI is older than the newest
published `opensymphony` release and only runs `cargo install opensymphony`
when it actually needs to. If the current directory already looks like an
OpenSymphony target repo because it has both `WORKFLOW.md` and `config.yaml`,
the command then refreshes changed or new files under `.agents/skills/`.
The template repository is still the upstream source of those starter assets,
but it is an implementation detail of `opensymphony init`, not a required
manual setup step:
- [kumanday/OpenSymphony-template](https://github.com/kumanday/OpenSymphony-template)
- [Raw template base](https://raw.githubusercontent.com/kumanday/OpenSymphony-template/refs/heads/main/WORKFLOW.md)
## Files Added By `init`
Core bootstrap payload:
- `WORKFLOW.md`
- `AGENTS.md`
- `config.yaml`
- `.gitignore` created or updated to ignore OpenSymphony runtime state
- `.agents/skills/` copied recursively, including skill-local `references/`, `scripts/`, and similar helper files
- `.agents/skills/linear/references/`
- `.github/CODEOWNERS`
- `.github/pull_request_template.md`
## Refreshing Template Skills
`opensymphony update` only refreshes template-managed files under
`.agents/skills/`.
It does not:
- rerun the interactive `init` prompts
- modify `WORKFLOW.md`
- merge or rewrite `AGENTS.md`
- copy `.github/*` bootstrap files
- delete repo-local extra skills that are not in the template tree
Optional AI PR review scaffolding:
- `.github/workflows/ai-pr-review.yml`
- `.agents/skills/custom-codereview-guide.md`
## Labels
If you enable AI PR review and `gh` is available with repository access,
`opensymphony init` can create the `review-this` label for you. If automation is
skipped, create it once per repository:
```bash
gh label create "review-this" --description "Trigger AI PR review" --color "d73a4a" --force
```
## Review The Generated Workflow
After `init`, review `WORKFLOW.md` and `config.yaml`.
Important fields:
| `tracker.project_slug` | Linear `Project.slugId` from the project URL | - | `my-project-5250e49b61f4` |
| `workspace.root` | Where to store per-issue workspaces | - | `~/.opensymphony/workspaces` |
| `openhands.conversation.agent.llm.model` | LLM model to use | `LLM_MODEL` | `openai/accounts/fireworks/models/glm-5p1` |
For Linear trackers, `tracker.project_slug` should store the project's
`slugId`, not a `team/project` path.
## Environment Variables
OpenSymphony uses standard OpenHands environment variable names.
Fireworks example via the OpenAI-compatible provider adapter:
```bash
export LLM_MODEL="openai/accounts/fireworks/models/glm-5p1"
export LLM_API_KEY="fw-..."
export LLM_BASE_URL="https://api.fireworks.ai/inference/v1"
```
The workflow supports `${VAR}` syntax for environment variable substitution in
the front matter:
```yaml
openhands:
conversation:
agent:
llm:
model: ${LLM_MODEL}
```
## Conversation Condensation
Optional conversation condensation is enabled by default per workflow to reduce
long-history context pressure before the agent-server hits the model window:
```yaml
openhands:
conversation:
agent:
condenser:
max_size: 240
keep_first: 2
```
OpenSymphony forwards an OpenHands `LLMSummarizingCondenser` that reuses the
conversation agent's LLM settings. The condenser is enabled by default with
`max_size: 240` and `keep_first: 2`. To disable it, set `enabled: false`.
## Runtime Config
`opensymphony init` also copies a starter `config.yaml` next to the target
repository `WORKFLOW.md`.
Minimal local-supervised example:
```yaml
control_plane:
bind: 127.0.0.1:2468
openhands:
tool_dir: ~/.opensymphony/openhands-server
memory:
auto_capture: true
auto_archive: false
```
Provision that app-managed directory with:
```bash
opensymphony install openhands
```
When your workflow points at an external OpenHands agent-server with
`openhands.transport.session_api_key_env`, `config.yaml` can omit
`openhands.tool_dir`.
Use [examples/target-repo/config.yaml](../examples/target-repo/config.yaml) as
the starting template if you want to inspect the checked-in example.
[examples/configs/local-dev.yaml](../examples/configs/local-dev.yaml) is a
developer-facing doctor fixture for this repository. It is not the runtime
config that `opensymphony run` looks for in a target repo.
## Memory Configuration
Project memory stores runtime state under `.opensymphony/memory` and can be
captured automatically by `opensymphony run`. Runtime automation is controlled
by `config.yaml`:
```yaml
memory:
auto_capture: true
auto_archive: false
```
`auto_capture` defaults to `true`. It captures terminal issue transitions
observed by the run loop. `auto_archive` defaults to `false`; when enabled, it
archives only after successful capture with no blocking warnings.
Initialize the shared memory policy and learned ontology file with:
```bash
opensymphony memory init
```
This creates `.opensymphony/memory/memory.yaml` and updates `.gitignore` so only
that shared config is tracked. Capsules, markdown indexes, DuckDB, source
snapshots, and runtime logs remain local:
```text
.opensymphony/memory/
memory.yaml
issues/
indexes/
memory.duckdb
```
`memory.yaml` contains policy plus learned structure. `memory init` seeds stable
areas from existing top-level `docs/*.md` files when present; otherwise it
starts with an empty `areas` map and capture evolves it from Linear and PR
narrative evidence:
```yaml
memory_root: .opensymphony/memory
visibility: private
index_path: .opensymphony/memory/memory.duckdb
confidence_threshold: 75
markdown_indexes: true
docs:
public_root: docs
default_visibility: public
deny_private_links: true
areas:
openhands-runtime:
title: OpenHands Runtime
docs_target: docs/openhands-runtime.md
visibility: public
status: stable
confidence: 85
aliases:
- OpenHands Runtime
source_refs:
docs:
- docs/openhands-runtime.md
linear_labels:
- runtime
```
Private memory should stay out of source control. Commit
`.opensymphony/memory/memory.yaml` and generated public docs when appropriate;
do not commit issue capsules, markdown indexes, DuckDB, source snapshots, or
runtime state.
## OpenHands PR Review
If you opt into OpenHands PR review during `init`, the CLI will try to
configure the GitHub Actions variables, label, and optional review secret for
you when:
- `gh` is installed
- `gh` can access the target repository
- you approve the automation prompt
If any of those are missing, `init` falls back to a short checklist plus the
manual `gh` commands. The full verification and branch-protection guidance
lives in the OpenSymphony docs at
[ai-pr-review-human-setup.md](ai-pr-review-human-setup.md); `init` does not
copy that guide into the target repository.
## Current model
- COE-286 contributed: PR #49: Abort active CLI worker tasks on graceful shutdown (merge `2c839fd`)
- COE-288 contributed: PR #51: Add configurable OpenHands context condenser support (merge `102a93c`)
- COE-293 contributed: PR #56: fix: add OpenHands filesystem tools to coding agents (merge `2f34058`)
## Important invariants
- Preserve the behavior described in the recent captured changes unless current code and tests show it has changed.
- Use capsule source refs to inspect the original PR or Linear issue when context is ambiguous.
## Operational flow
```mermaid
flowchart TD
memory["Captured issue memory"] --> area["Configuration"]
area --> docs["docs/configuration.md"]
```
## Known gotchas
- No area-specific gotchas were inferred from the selected memory.
## Recent changes
- COE-286: Abort active CLI worker tasks on graceful orchestrator shutdown
- COE-288: Add context condenser support to prevent LLM context window overflow
- COE-293: OpenHands agent has no filesystem tools - only FinishTool and ThinkTool
## Source refs
- COE-286
- COE-288
- COE-293