skyline

A search-and-edit toolkit that lets AI coding assistants change your code safely. Every edit is bound to a content fingerprint and refused if the file changed since it was read, so an assistant never silently overwrites your work. Search and refactoring understand code structure, not just text.

Install

The recommended setup is a small always-on background service (a daemon) that your AI client talks to. Start it once and every tool call is fast.

• No cold starts: the warm daemon answers a full tools/list round-trip in 10 to 40 ms — no per-session startup.
• Language servers stay warm: the one-time cold index on a ~224k-line workspace took 95 s; warm calls are sub-second. With a daemon that price is paid once per workspace, not once per session.
• One process for every client: Claude Code, other MCP clients, and scripts all share the same warm state, one audit stream, and one bench stream.
• See docs/benchmarks.md for full numbers.

1. Install (npm — prebuilt binary, every platform)

npm install -g @skylence-ai/skyline

Puts the skyline binary on your PATH (macOS arm64/x64, Linux arm64/x64, Windows x64/arm64) via the matching @skylence-ai/skyline-<platform> optional dependency — no native installer or compile step. Alternatives: cargo binstall skyline, or a prebuilt archive from GitHub Releases.

2. Bootstrap the daemon and plugins

skyline setup

skyline setup is the idempotent, cross-package-manager setup path. It installs the shared HTTP daemon as a supervised autostart service on port 7333 and best-effort installs the Skyline marketplace plugins for agent CLIs already on PATH. Re-run with skyline setup --force after changing agent installs or PATH.

npm may run this for you as a best-effort postinstall hook, but modern package managers can block lifecycle scripts. If in doubt, run skyline setup once.

Check it is up with skyline daemon status (the port should read running). To remove the setup-installed daemon, optional plugins, package-manager install, skyline-owned dispatchers, and any legacy Skyline agent wiring, run skyline uninstall --full. Other install methods are in docs/install.md.

3. Prompts for your agent

Paste this into your agent's instructions so it picks the right tool:

Prefer skyline's MCP tools over your built-in file read, edit, and search tools for all code work, and especially when a skyline HTTP MCP server is registered (a shared, always-warm daemon, so calls stay cheap). If skyline becomes unavailable mid-session (tools dropped from your tool list, connection refused or closed), do NOT silently fall back to your built-in tools: retry once, then pause code work, report the outage to your orchestrator or user, and wait for skyline to be restored before continuing. Use `skyline_tree` to get project shape and orient in an unfamiliar repo (every output line is a plain path you pass straight to `skyline_read`), `skyline_read` to read a file (it returns a `¶path#TAG` anchor; never reconstruct that header by hand, copy it back verbatim), `skyline_grep` for regex/text search, `skyline_sgrep` for structural/AST search, `skyline_edit` to apply hash-guarded line edits using that anchor, `skyline_srewrite` for one-pass structural find-and-replace across a file or directory, and `skyline_format` to run the language formatter (rustfmt, gofmt, prettier) through the audited pipeline; use `skyline_git` for repo status and compressed unstaged diffs (context stripped, each file section headed by a real `¶path#TAG` anchor so you can edit straight from the diff output), and `skyline_test` to run the test suite (failures come back with `¶path#TAG` anchors for direct editing; `exit_code` is authoritative — a nonzero exit with no parsed failures means a build error, consult the raw output path); use `skyline_run` with an argv ARRAY (never a shell string; there is no shell) for any simple command such as git, cargo, docker, gh, or npm (output comes back compressed with the full raw output teed to a temp file and the invocation audited; to run several commands in one round-trip pass `argv_list`, an array of argv arrays, optionally with `parallel: true`, and supply exactly one of `argv` or `argv_list`), falling back to your built-in Bash tool only for compound shell features (pipes, &&, redirection, command substitution); use `skyline_json` to query or reshape JSON without paying tokens for or leaking the values, instead of piping a file through Bash and jq; when the task is about a SYMBOL rather than text, use the semantic tools: `skyline_definition` (where is it defined, starting from a call site), `skyline_references` (every true caller; comments and strings never match), `skyline_rename` (whole-workspace rename, preview with dry_run), `skyline_symbols` (find by name fragment), and `skyline_diagnostics` (does the file still typecheck after an edit; per-file, so use the build tool for whole-project checks); always read (or grep/sgrep) to get a fresh anchor before editing, pass it back unchanged, and if an edit is rejected as stale, re-read to refresh the tag and retry. For observability (off by default): `skyline_observability_status` to see what is enabled, `skyline_observability_set` to toggle the audit/devlog/bench streams, `skyline_audit_tail` and `skyline_log_tail` to read the mutation-audit and diagnostic logs, `skyline_bench_report` for timing aggregates, and `skyline_audit_prune` / `skyline_devlog_prune` / `skyline_bench_prune` to trim them.

Or skip the manual setup entirely and hand your agent this:

Set up skyline for me: install it with `npm install -g @skylence-ai/skyline` (prebuilt binaries for every platform, incl Windows arm64), run `skyline setup` to install the shared HTTP MCP daemon as a supervised autostart service and install the Skyline marketplace plugins when Claude or Codex CLIs are available, then verify: `skyline daemon status` must show port 7333 as `running`, and the agent's plugin/MCP list or status command must show skyline as connected. Do NOT probe the endpoint with raw curl: it is a stateful streamable-HTTP MCP server that requires an initialize handshake, an Accept header for both application/json and text/event-stream, and a session id, so ad-hoc curl calls fail by design; the agent's MCP status command is the correct connectivity check, and the tools (e.g. `skyline_version`) become callable in your next session. If the port is taken, run `skyline daemon install --port <free-port>` and configure the plugin or explicit agent wiring to `http://127.0.0.1:<free-port>/mcp`.

The numbers

The search result IS the edit handle, so edit cost stays flat (~60 tokens whether the file is 300 lines or 10,000). Four blind evaluation rounds, measured with skyline's own bench stream:

• Every mid-edit race became a one-line rejection, never a silent overwrite. Two agents editing the same file simultaneously, blind to each other: zero lost updates (docs/concurrency.md).
• Repo-scale questions answered in one line instead of a match dump.
• A 404-file rewrite converged in one extra call; the residual report said exactly what remained and why.
• Under drift, conflicts, and out-of-band edits, a blind agent re-grounded before editing and reconstructed the change history from the audit stream.

| | Built-in read→edit | skyline | |---|---|---| | One edit in a 10,000-line file | ~83,500 tokens | ~62 tokens (1,336× less) | | Repo-wide structural count (896 Go files) | full match dump, no exact total | 1 line: 282 matches in 105 files. | | 213-file structural rewrite | no built-in equivalent | 3 calls, ~8.3k tokens, previewed + hash-guarded |

Measured, not modeled: methodology and full tables in docs/benchmarks.md.

What problem does this solve?

• Silent overwrites. If a file changed after the assistant read it (you saved, a formatter ran), text-matching edits quietly destroy work. skyline fingerprints every read and refuses stale edits.
• Text-blind search. Find-and-replace renames hit comments and strings. skyline rewrites by structure: real calls change, comments stay.
• Token bloat. Read-then-edit costs grow with file size; search returns dumps. skyline replies stay small: ~60-token edits, one-line counts, per-file rewrite summaries. Up to 48% less traffic on combined tasks; one blind run took 14 round-trips where built-ins needed ~450.
• Cold starts. The daemon keeps one warm process (and warm language servers) for every client.

Why it is better

These come from running skyline against real repositories and measuring with its own tools. Full detail and the methodology are in docs/benchmarks.md.

• Safe edits, proven. When a file changed between read and write, skyline refused the edit rather than overwriting it. A plain string-matching editor has no such guard.
• Refactors that respect code. Rewriting a Go call changed 18 of 18 real call sites and left an identical word inside a comment untouched. A sed find-and-replace would have corrupted that comment.
• No search penalty. A controlled query returned the same 66 matches as ripgrep, because skyline uses the same engine and gitignore-aware walk.
• No startup tax. The warm daemon answers in 10 to 40 ms with no per-session startup.

Tools

skyline is one Rust binary with two faces: a command-line tool and an MCP server for AI clients.

| Capability | CLI | MCP tool | |------------|-----|----------| | Read a file with a content fingerprint | skyline read | skyline_read | | Apply a fingerprint-guarded edit | skyline edit | skyline_edit | | Patch format reference | skyline preview | skyline_format | | Regex search (ripgrep engine) | skyline grep | skyline_grep | | Structural search (ast-grep) | skyline sgrep | skyline_sgrep | | Structural rewrite (ast-grep) | skyline srewrite | skyline_srewrite | | Where a symbol is defined | | skyline_definition | | Every real caller of a symbol | | skyline_references | | Rename a symbol everywhere, safely | | skyline_rename | | Find a symbol by name fragment | | skyline_symbols | | Does the file still compile after an edit | | skyline_diagnostics | | Project shape / orientation (tree) | | skyline_tree | | Git status and compressed diff with anchors | | skyline_git | | Run tests, failures-only with anchors | | skyline_test | | Version and tool-manifest digest | skyline version | skyline_version | | Observability streams (audit, devlog, bench) | skyline audit/devlog/bench | skyline_observability_*, tail and prune tools | | Manage the background daemon | skyline daemon … | (CLI) | | Start the daemon on every boot | skyline daemon install | (CLI) | | Bootstrap daemon + plugins | skyline setup | (CLI) | | Health check | skyline doctor | (CLI) |

Understanding code, not just matching text

The five symbol tools (definition, references, rename, symbols, diagnostics) answer questions text search cannot: where a function is really defined, who actually calls it (the same word in a comment does not count), and how to rename it everywhere in one safe step. skyline does this by talking to the same "language brain" your editor uses (a language server). Two things to know: that brain is a separate program installed once per language, and skyline prints the exact install command if it is missing; and the first question in a project takes a few seconds while the brain reads your code, after which answers are instant. Setup and details: docs/lsp.md.

Language support

| Language | Extensions | sgrep/srewrite | LSP (definition, rename...) | Block ops | Test runners | |----------|------------|:--------------:|:---------------------------:|:---------:|--------------| | Rust | .rs | yes | rust-analyzer | yes | cargo-test | | Go | .go | yes | gopls | yes | go-test | | TypeScript | .ts .tsx .mts .cts | yes | typescript-language-server | yes | vitest, jest | | JavaScript | .js .jsx .mjs .cjs | yes | typescript-language-server | yes | vitest, jest | | Python | .py .pyi | yes | pyright-langserver | yes | pytest | | PHP | .php | yes | intelephense / phpactor | yes | pest, phpunit | | C | .c .h | yes | clangd | yes | | | C++ | .cc .cpp .cxx .hh .hpp .hxx | yes | clangd | yes | | | Ruby | .rb | yes | ruby-lsp | yes | rspec, rake-test | | Java | .java | yes | jdtls | yes | | | Swift | .swift | yes | sourcekit-lsp | yes | swift-test | | Kotlin | .kt .kts | yes | kotlin-language-server | yes | | | HTML | .html .htm | yes | | | | | JSON | .json | yes | | | | | YAML | .yaml .yml | yes | yaml-language-server | | | | CSS | .css | yes | | | | | Markdown | .md .mdx .markdown | | marksman | | | Adding a language: docs/add-a-language.md.

How it works

read prints a file with a ¶path#TAG header and numbered lines. That header is the edit anchor: pass it back verbatim to edit. The tag is a 4-hex CRC32 of the normalized content, so a changed file produces a different tag and a stale edit is rejected (and recovered via 3-way merge when possible). grep and sgrep return the same ¶path#TAG headers, so search output feeds straight into an edit. srewrite rewrites by structure in one pass and can preview with --dry-run.

Details: edit and patch format, grep, structural search and rewrite, the content tag, stale-edit recovery.

Documentation

• docs/install.md: all install methods
• docs/benchmarks.md: benchmarks, findings, and methodology
• docs/cli.md: full CLI reference, including daemon, doctor, version
• docs/mcp.md: MCP server, transports, client config, and tool descriptions
• docs/grep.md: grep reference (flags, output format, parallelism)
• docs/sgrep.md: structural search and rewrite reference
• docs/lsp.md: the semantic tools (definition, references, rename, symbols, diagnostics)
• docs/patch-format.md: patch sections and operations
• docs/content-hash.md: the CRC32 content tag
• docs/block-operations.md: tree-sitter replace block / delete block
• docs/add-a-language.md: how to wire a new language into the registry
• docs/recovery.md: stale-tag recovery and snapshot storage
• docs/observability.md: audit, devlog, and bench streams
• docs/npm-distribution.md: how skyline ships to npm
• AGENTS.md: agent-facing conventions

More benchmarks

From a blind production run (1.0.10, fresh agent, hugo's 896 Go files; all numbers from skyline's own bench stream):

• All six tasks (a 7-file semantic rename, workspace symbol search, two repo-wide structural counts, a YAML rule diagnosis, and the 213-file rewrite) cost ~16.8k output tokens total. An earlier release spent 86k on a single rewrite preview alone; the summary preview cut that by ~99.7%.
• Per-edit cost is flat against file size: ~49 tokens on a 292-line file, ~62 on a 10,496-line file. The naive read-then-edit flow grows linearly (~2.1k → ~83.5k); even a skilled grep→windowed-read→edit flow runs 12-17× skyline's cost.
• Batched diagnostics covered 7 renamed files in one call (~248 tokens). The one-time language-server cold index on a ~224k-line workspace took 95 s; warm calls are sub-second.
• Edit input has held at ~57 tokens p50 across releases: anchors keep file content out of the edit round-trip entirely.

Full tables, the 1.0.5 safety/parity/transport baselines, and honest caveats: docs/benchmarks.md.

License

Apache-2.0. See LICENSE.