# Work with Koharu Agent
Source: https://koharu.rs/en/agent/projects

Ask the Agent to inspect pages, edit content, and run the configured pipeline.

Give the Agent a concrete goal within the currently open project. Name the pages, desired change, and anything it should leave untouched.

## Write a scoped request

<Tabs>
  <Tab title="Text review">
    > Review pages 3–5. Correct obvious OCR errors and translate into natural English while preserving honorifics. Keep typography unchanged.
  </Tab>

  <Tab title="Visual review">
    > Check whether the text on page 8 overflows its bubble. Adjust only the size and line breaks.
  </Tab>
</Tabs>

Semantic inspection is sufficient for many text edits. Ask for visual inspection when appearance matters.

## Available actions

The Agent can inspect current semantic state, render a particular page, rename/reorder/delete pages, add paragraph text boxes, edit source text and translations, change typography and geometry, adjust visibility and opacity, move or delete elements, and run the configured pipeline for project, page, or text-element scopes.

<Note>
  The project tools do not import source files, export files, manage provider credentials, or
  operate outside the open project.
</Note>

## Edits, cancellation, and history

Agent changes use the same project operations as the desktop UI. Successful edits update the scene, renderer, revision, and undo history.

Pipeline runs commit completed stages incrementally. An Agent-started run does not appear in the activity center, but it blocks other processing until it finishes. Canceling the Agent request also asks an Agent-started pipeline to stop cooperatively. Only one Agent request runs at a time.

<Steps>
  <Step title="Inspect the changed pages">Review source text, translations, and the canvas.</Step>
  <Step title="Check the layout">Verify geometry and typography at normal reading size.</Step>

  <Step title="Keep or undo the change">
    Use undo for unwanted changes, and export after your review.
  </Step>
</Steps>


# Set up Koharu Agent
Source: https://koharu.rs/en/agent/setup

Sign in with ChatGPT and configure the integrated project assistant.

Koharu Agent is a Codex client inside the editor. It uses ChatGPT device-code sign-in; you do not enter an OpenAI API key for the Agent.

<Steps>
  <Step title="Open the Agent panel">Open a project and select **Agent** on the right.</Step>

  <Step title="Authorize the device">
    Choose **Sign in with Codex**. Koharu opens the authorization page in your browser; enter the
    code shown in the panel and approve the sign-in for your account. The code expires after 15
    minutes.
  </Step>

  <Step title="Choose a model">
    Return to Koharu and wait for the account and model list. Select a Codex model and reasoning
    level at the top of the Agent panel; **Automatic** uses the first available model. More
    reasoning can help with ambiguous edits but takes longer.
  </Step>
</Steps>

Only one sign-in attempt can run at a time. Cancel it before starting another.

## What context is shared

The Agent starts with the open project's semantic state. It renders and attaches a page image only when it invokes visual page inspection; it does not automatically attach every page.

<Note>
  Agent sign-in and translation-provider credentials are separate. ChatGPT sign-in does not
  configure the pipeline's OpenAI provider, and an OpenAI API key does not sign in the Agent.
</Note>

## Sign out

**Sign out** cancels active work, clears the current Agent session, and removes the Codex account authorization used by Koharu. Opening or closing a project also clears the conversation. Agent configuration is saved separately from translator settings.

<Card title="Work with a project" icon="comment" href="/en/agent/projects">
  Give the Agent a precise scope, review its edits, and use project history.
</Card>


# Architecture
Source: https://koharu.rs/en/development/architecture

Follow ownership from the React interface to scenes, processing, and native runtimes.

Koharu runs as a desktop application. React invokes typed Tauri commands; native components own durable project state and processing.

```mermaid theme={null}
flowchart TB
  ui["packages/koharu: React + Next.js"] --> bridge["packages/bridge: protocol + WASM"]
  entry["crates/koharu: startup"] --> app["koharu-app"]
  bridge -->|"commands and channels"| app
  app --> scene["koharu-scene"] --> storage["koharu-storage"]
  app --> pipeline["koharu-pipeline"] --> ml["koharu-ml"] --> runtime["koharu-runtime"] --> native["native runtimes"]
  app --> translator["koharu-translator"]
  app --> agent["koharu-agent"]
  app --> desktop["koharu-desktop"] --> renderer["koharu-renderer"] --> rasterizer["koharu-rasterizer"]
  bridge --> canvas["koharu-canvas"] --> rasterizer
  app --> psd["koharu-psd"] --> renderer
  psd --> rasterizer
```

## Interface and application

| Component | Responsibility |
| - | - |
| `packages/koharu` | Project browser, page rail, canvas controls, inspector, settings, activity, Agent, and transient interaction state |
| `packages/ui` | Shared React primitives and styling |
| `packages/bridge` | Generated Tauri protocol, browser canvas adapter, and derived WASM package |
| `crates/koharu` | Startup, diagnostics, Tauri configuration, and build integration |
| `koharu-app` | Tauri state, project lifecycle, command serialization, jobs, synchronization, and Agent hosting |

Independent typed channels carry project, canvas, job, download, and resource updates; Agent sign-in and runs stream through per-call channels. Preferences are fetched and saved through commands. The frontend does not use an HTTP client or a generic application event envelope.

<Note>
  Rust signatures generate `packages/bridge/src/protocol.ts`. Change the Rust source and [regenerate
  bindings](/en/development/setup#regenerate-ipc-bindings).
</Note>

## Scene and processing

`koharu-scene` owns the canonical project, hierarchy, components, relations, patches, revisions, and session undo. `koharu-storage` persists opaque complete state payloads and immutable blobs.

`koharu-pipeline` owns page-stage scheduling, model lifetime, progress, cancellation, and incremental commits. `koharu-ml` owns models and the shared device abstraction; `koharu-translator` owns local and hosted translation connections.

## Rendering and transport

`koharu-renderer` interprets a page as a portable prepared frame owned by `koharu-rasterizer`. Browser transport splits its manifest from content-hashed resources. Raster data is tiled with sampling gutters, bounding browser copies, validation, uploads, and eviction.

`koharu-canvas` retains resources across pages and activates a staged frame through WebGPU only when every dependency is ready. Native PNG, PSD, font previews, and Agent previews compose the same full-resolution resources through native readback.

`koharu-desktop` coordinates latest-wins preparation and exact-generation manifests and resources. The webview owns the visible window surface.

## Native runtime boundary

Safe wrappers `koharu-torch`, `koharu-llama`, and `koharu-diffusion` are separate from unsafe `-sys` dynamic-loading crates. `koharu-runtime` discovers, downloads, validates, and loads their packages.

Three crates are shared across the diagram and omitted from it: `koharu-config` owns the typed sections of `config.toml`, `koharu-secrets` wraps the operating system credential store, and `koharu-metrics` collects telemetry.

<CardGroup>
  <Card title="Scene and storage" icon="database" href="/en/development/scene">
    Trace edits, revisions, publication, and recovery.
  </Card>

  <Card title="Processing and rendering" icon="layer-group" href="/en/development/rendering">
    Follow stage commits through browser presentation.
  </Card>
</CardGroup>


# Contribute to Koharu
Source: https://koharu.rs/en/development/contributing

Prepare a focused change that the project can review and maintain.

Bug fixes, documentation, translations, model-port corrections, and focused product improvements are welcome. Start with [good first issues](https://github.com/koharu-rs/koharu/contribute), search existing [issues](https://github.com/koharu-rs/koharu/issues) and pull requests, or discuss scope on [Discord](https://discord.gg/mHvHkxGnUY).

<Steps>
  <Step title="Agree on the problem and scope">
    Small fixes and documentation changes can usually be submitted directly. Before building a new feature, significant UI change, model, provider, platform integration, dependency, public API, schema change, or architectural refactor, discuss the problem and direction in an issue.

    An issue, working implementation, or agreed direction does not guarantee acceptance.
  </Step>

  <Step title="Follow the owning component">
    Read the affected crate's README and repository rules. Update every in-repository consumer when APIs or schemas change; do not add compatibility aliases. Keep provider defaults with their provider and safe APIs separate from unsafe FFI and dynamic loading.

    Preserve checkpoint-affecting structure in model ports. Compare structured outputs on identical inputs. Explain ownership, invariants, upstream mapping, or deliberate divergences in comments.
  </Step>

  <Step title="Verify the change">
    Review the whole diff. Run the smallest relevant debug check or focused test once, format affected code, and run `git diff --check`.

    Supply screenshots for UI changes, device/input/baseline/result/correctness for performance work, and structured comparisons for model ports. State any checks that could not run.
  </Step>

  <Step title="Open a focused pull request">
    Explain the problem, solution, important behavior or ownership changes, and validation. Keep unrelated refactoring out. Be ready to revise the change and ask when review feedback is unclear.
  </Step>
</Steps>

Do not commit credentials, model weights, datasets, generated output, build artifacts, or machine-specific files.

## How proposals are evaluated

Maintainers consider product fit, breadth of user value, UX, architecture, performance, security, privacy, platform support, tests, documentation, dependencies, and operational complexity.

A proposal may be declined, postponed, reduced in scope, redesigned, or kept outside the core project. Once merged, its maintenance becomes the project's responsibility. Continued contributor help is welcome, but the project must be able to support the feature if that availability changes.

## AI-assisted contributions

A human contributor must remain the author and owner of a submission.

Before submitting, personally review the complete diff, verify generated claims against code, reproduce reported problems, understand the changes and edge cases, and be able to revise them. Provide the same checks and evidence as any other contribution.

<Warning>
  Do not submit autonomous or unreviewed issues, pull requests, review comments, or security
  reports. Treat generated output as a draft, and make descriptions and review responses reflect
  your own understanding.
</Warning>

Maintainers may close submissions that appear unreviewed, contain speculative or fabricated claims, cannot be explained or revised, or require more review effort than the value they offer. Ask if you are unsure how these expectations apply.

Continue with [development setup](/en/development/setup).


# Write and publish docs
Source: https://koharu.rs/en/development/documentation

Preview Mintlify, maintain translated MDX, and connect the repository for publishing.

The documentation is the `@koharu/docs` Mintlify workspace in `packages/docs/`. Bun manages its dependencies through the repository's root `bun.lock`.

<Steps>
  <Step title="Install the docs tooling">
    Use Node.js 24 LTS and Bun 1.3.14 or later. From the repository root:

    ```bash theme={null}
    bun install --frozen-lockfile --ignore-scripts
    ```
  </Step>

  <Step title="Preview">
    ```bash theme={null}
    bun run docs
    ```

    Open `http://localhost:3001`. The preview updates when MDX or configuration changes.
  </Step>
</Steps>

## Author native MDX

Every page needs a `title` and `description` in frontmatter. Mintlify renders article titles, so do not repeat them as an H1. The landing pages use Almond's native `frame` mode and provide their own single H1.

Use **Steps** for ordered tasks, **Tabs** for platform or model choices, **Note**, **Tip**, and **Warning** for relevant callouts, **Cards** for next actions, and **Accordions** for symptom-specific help. Keep reference tables and fenced Mermaid diagrams readable without custom scripts or CSS.

Use root-relative internal links with no file extension, such as `/en/guides/export`. Shared images live outside the locale folders and need descriptive alt text.

## Keep translations aligned

English, Japanese, and Simplified Chinese live in `en/`, `ja/`, and `zh/`. Maintain matching page slugs, instructions, examples, and technical coverage in all three languages. Translate headings, descriptions, component labels, navigation, and image descriptions as well as prose.

`packages/docs/docs.json` owns themes and navigation. Add a page to every language's navigation when it is introduced. The site uses Mintlify's language switcher and does not keep old Zensical routes or redirects.

## Connect publishing

In the Mintlify dashboard, connect `koharu-rs/koharu` and select the production branch. In Git Settings, enable **docs.json is in a subdirectory** and enter `/packages/docs` without a trailing slash. Configure `koharu.rs` as the custom domain and follow the DNS records shown by Mintlify.

<Note>
  Publishing and custom-domain activation require the Mintlify GitHub integration and domain
  configuration.
</Note>

See Mintlify's [monorepo setup](https://www.mintlify.com/docs/deploy/monorepo) and [custom domains](https://www.mintlify.com/docs/customize/custom-domain) for dashboard instructions.


# Processing and rendering
Source: https://koharu.rs/en/development/rendering

Follow incremental stage results through retained frames and the WebGPU canvas.

## Schedule the fixed pipeline

`koharu-pipeline` schedules one stage on one page as its execution unit:

```mermaid theme={null}
flowchart LR
  detection["Detection"] --> ocr["OCR"] --> translation["Translation"]
  detection --> inpainting["Inpainting"]
```

Pages enter in project order. Completed detection makes that page's dependent branches eligible immediately, without waiting for detection on the whole project. At most one job per stage runs at a time, and the number of pages in flight is bounded by the number of selected stages.

Stages return semantic patches. The application commits each result, synchronizes the canvas, and records each commit as its own undo step.

## Manage residency and stopping

Accelerator inference uses one admission lane: representative heterogeneous overlap reduced throughput through compute and memory-bandwidth contention. The translation stage takes the lane for every provider, including remote APIs. CPU-only work can keep independent per-model lanes.

Models load lazily and remain reusable. When a stage fails with an out-of-memory error, the runner releases the accelerator lane, unloads the other stages' models, waits briefly for a fresh resource sample, and retries once. Any other failure unloads the failing stage's model. A settings change rebuilds the stage runner, so models reload on the next run.

Stopping is cooperative. New stages do not start after a stop request. Active native inference returns safely; an uncommitted result is discarded.

## Prepare a retained frame

`koharu-renderer::Renderer` turns a scene snapshot and page ID into an immutable `Frame` with ordered layers, entity lookup, presentation metadata, dependencies, diagnostics, and vector scenes. It prepares a portable `koharu-rasterizer` bundle for browser display and native readback.

Translation is the only visible text source. Typography, fit relations, fonts, images, visibility, and opacity come from the scene. Callers do not supply a second document model.

<Note>
  WebGPU presentation, PNG, layer crops, and PSD consume the same prepared frame. Incremental reuse
  must produce the same result as a full render.
</Note>

## Present in the browser

The Tauri CEF webview owns the visible surface. React draws the interface; `koharu-canvas` compiles to WASM and renders to an `HTMLCanvasElement` with WebGPU. Camera motion, transform previews, strokes, and sampling stay transient in the browser. Completed edits cross Tauri commands.

<Steps>
  <Step title="Publish a generation">
    A page change announces a generation before its lightweight manifest is requested.
  </Step>

  <Step title="Fetch missing resources">
    The canvas reports missing content IDs and receives resource packets asynchronously.
  </Step>

  <Step title="Activate the complete frame">
    The previous page remains visible until the staged generation is ready. Obsolete preparation or
    requests cannot replace a newer generation.
  </Step>
</Steps>

Raster resources use 1024-pixel logical tiles with one-pixel interior sampling gutters. These bound WASM copies and GPU textures while preserving filtered edges. Coordinated CPU/GPU caches avoid resending or uploading unchanged resources when revisiting pages.

## Inspect the desktop result

Validate visual changes in the final Tauri window: adapter availability, device loss, sizing, and display scaling depend on the webview. Native PNG and PSD checks cover the shared readback path.

Debug builds expose CEF at `http://127.0.0.1:4000`. Use semantic CDP inspection for DOM and canvas lifecycle, and native window capture for final pixels.


# Scene and storage
Source: https://koharu.rs/en/development/scene

Understand semantic edits, immutable snapshots, and durable project publication.

`koharu-scene` owns what a project means. `koharu-storage` owns how complete states and immutable bytes become durable.

## Separate analysis, content, and presentation

Projects contain ordered pages. Each page has stable external entity IDs, a local arena, hierarchy, typed components, and relations.

```mermaid theme={null}
flowchart BT
  presentation["TextLayout + Typography + optional authored Geometry"]
  content["TextContent + SourceText + Translation"]
  analysis["Region + Geometry + OCR analysis"]
  presentation -->|"presents"| content
  content -->|"recognized-from"| analysis
```

Detection geometry stays analysis rather than becoming a movable visible layer. Translation can change without losing OCR provenance; typography can change without rewriting semantic text.

## Apply an edit

Snapshots are immutable and cheap to clone. A patch binds to a project and base revision, records operation preconditions, and carries inverses for session undo.

<Note>
  A stale patch is not accepted silently. Derived work must explicitly rebase, and rebasing fails
  when anything the patch observed has changed since its base revision.
</Note>

## Publish a state

Storage is domain-agnostic. It saves an opaque complete scene payload into alternating `state-a.khr` and `state-b.khr` slots, with immutable content-addressed blobs, checksums, and a referenced-blob set.

<Steps>
  <Step title="Publish missing blobs">
    Make referenced bytes available before publishing the state that needs them.
  </Step>

  <Step title="Write the inactive state">
    Build the new slot beside its destination and flush it.
  </Step>

  <Step title="Publish atomically">
    Make the new slot durable while retaining the previously valid slot if publication fails.
  </Step>
</Steps>

## Recover and collect

Opening selects the newest valid state and can fall back to the other slot if the newer one is corrupt. Blob reads may use read-only memory mapping without exposing that detail to scene consumers.

Storage and scene expose a garbage-collection routine that preserves blobs referenced by both valid disk states and live scene scopes, including undo history. The application does not call it yet, so unreferenced blobs remain on disk.

## Keep application ownership separate

The application owns `.khrproj` directories, names, active-page selection, undo grouping, and UI projection. Renderer, pipeline, and Agent consume snapshots and submit semantic patches; they do not write storage files directly.


# Development setup
Source: https://koharu.rs/en/development/setup

Run the desktop app, choose a focused check, and regenerate derived bindings.

## Prerequisites

Koharu is developed against Rust 1.97.1 with the 2024 edition, Bun 1.3.14, and LLVM 22.1.8. The repository does not pin these versions. LLVM supplies the libclang that bindgen needs in the `-sys` crates; the native libraries themselves are prebuilt packages downloaded at runtime, so no C++ build system is required.

<Tabs>
  <Tab title="Windows">Install MSVC C/C++ build tools for native dependencies.</Tab>

  <Tab title="Linux">
    Install the packages the CI workflow uses: `build-essential`, `libgtk-4-dev`, `libxdo-dev`,
    `libssl-dev`, `libayatana-appindicator3-dev`, and `librsvg2-dev`. Tests also need
    `fonts-noto-cjk`, `dbus-x11`, and `gnome-keyring`.
  </Tab>

  <Tab title="macOS">
    Install the platform C/C++ development tools required by native dependencies.
  </Tab>
</Tabs>

## Start development

```bash theme={null}
git clone https://github.com/koharu-rs/koharu.git
cd koharu
bun install
bun dev
```

`bun dev` launches the Next.js UI and Tauri app. It builds `koharu-canvas` for WASM with wasm-pack into `packages/bridge/src/wasm`, then watches `koharu-canvas` and `koharu-rasterizer` and rebuilds on change. Turbopack refreshes the browser client after successful rebuilds. Debug builds expose CEF remote debugging at `http://127.0.0.1:4000`.

## Check the affected component

Run the smallest relevant debug check or focused test once. For example:

```bash theme={null}
cargo check -p koharu
cargo test -p koharu-pipeline <test_name>
cargo fmt --all --check
```

For frontend work, use the package's focused test or typecheck command. Repository formatting checks are available through `bun run check`; `bun run lint` runs frontend linting.

<Note>
  Do not run full suites, non-debug profiles, or end-to-end tests by default. Run them only when
  explicitly requested.
</Note>

## Regenerate IPC bindings

Rust command signatures and Specta types are authoritative:

```bash theme={null}
cargo run -p koharu-app --bin generate
```

Do not hand-edit `packages/bridge/src/protocol.ts`.

## Build an executable

When you need a release executable, `bun run build` invokes `tauri build --no-bundle` and writes to `target/release`. Installer packaging belongs to the release workflow.

<Card title="Work on the documentation" icon="book-open" href="/en/development/documentation">
  Preview Mintlify and maintain the English, Japanese, and Chinese documentation.
</Card>


# Use the canvas
Source: https://koharu.rs/en/guides/canvas

Navigate the page and choose the right tool for text, artwork, and cleanup.

The toolbar controls pointer behavior. The inspector changes the selected layer's saved properties.

## Navigate and select

Use **Pan** to move the view and the status bar to change zoom. **View → Fit Window**, or `0` by default, fits the active page. Switching pages returns to a fitted view.

Use **Select** to pick editable layers; hold `Shift`, `Ctrl`, or `Command` to add or remove layers. Text layers can be moved, resized, and rotated. Resize and rotate handles appear for a single selection; a multiple selection can only be moved. A drag previews the transform; finishing commits it, and canceling restores the previous presentation.

## Choose an editing tool

<Tabs>
  <Tab title="Text">
    Click with **Text** to create point text, or drag to create a paragraph frame. Enter the
    translation in the inspector and adjust [typography and fitting](/en/guides/typesetting).
  </Tab>

  <Tab title="Brush and Eraser">
    **Brush** paints on the selected raster layer with the chosen color and diameter, or creates a
    new Paint layer when no raster layer is selected. **Eraser** needs a selected raster layer. Both
    tools also accept the cleanup layer that inpainting produced; painting on it makes that layer
    yours. Hold `Alt` and scroll to change the diameter.
  </Tab>

  <Tab title="Color picker">
    Sample the composited canvas with **Color picker**. Apply the sampled color to brush strokes or
    text styling.
  </Tab>

  <Tab title="Remove">
    Paint over source marks with **Remove**. Releasing the stroke runs inpainting on that area
    immediately and merges the result into the page's cleanup layer; the mask is not kept as a
    layer. The stroke is rejected while another processing job is running. See
    [cleanup](/en/guides/cleanup).
  </Tab>
</Tabs>

<Tip>
  Hold `Space` or the middle mouse button and drag to pan without changing tools. Scroll to pan,
  hold `Shift` to pan horizontally, or hold `Ctrl` to zoom at the pointer. `Escape` cancels the
  active gesture and clears the selection.
</Tip>

Single-key tool shortcuts are inactive while a text field is focused. See [keyboard shortcuts](/en/reference/shortcuts).


# Clean up source lettering
Source: https://koharu.rs/en/guides/cleanup

Use inpainting and precise manual masks to remove lettering while preserving artwork.

Inpainting reconstructs the artwork beneath source text. A precise removal region usually matters more than a larger model.

## Review automatic cleanup

Detection produces a removal mask. Inpainting uses it to create a cleanup layer; without a mask, the stage completes without inference. The pipeline skips inpainting on a page that already has a cleanup layer, so use **Remove** to inpaint again.

Inspect the result at normal reading size and high zoom. Look for glyph fragments, missed punctuation or furigana, erased bubble borders, repeated textures, smeared screentone, and changes outside the lettering.

## Repair a missed region

<Steps>
  <Step title="Paint a removal mask">
    Choose **Remove**, set the brush diameter, and cover only the source marks that need
    reconstruction. Use controlled strokes and avoid neighboring line art. Cancel the gesture if the
    mask is wrong.
  </Step>

  <Step title="Let inpainting run">
    Release the stroke. Koharu runs inpainting for that area at once and merges the result into the
    page's cleanup layer. Include enough of each glyph for the model to remove it without covering
    an entire bubble unnecessarily.
  </Step>

  <Step title="Touch up and inspect">
    Use **Color picker**, **Brush**, and **Eraser** for small deterministic corrections. Check the
    result again at normal zoom.
  </Step>
</Steps>

Stopping a processing job does not turn its temporary removal mask into visible artwork.

## Choose a model

**LaMa** and **AOT** provide direct inpainting. **FLUX.2 Klein** and **RORem Mixed** are generative alternatives with prompt controls and larger resource requirements. See [vision and inpainting models](/en/models/vision).

<Warning>
  **Brush** strokes made while the cleanup layer is selected land on that layer, and a later
  **Remove** stroke merges into it. Clear the selection before painting to keep manual touch-ups on
  a separate Paint layer.
</Warning>


# Export PNG and PSD
Source: https://koharu.rs/en/guides/export

Export selected pages as flattened images or layered documents.

Review the page composite before choosing **File → Export PNG** or **File → Export PSD**.

<Steps>
  <Step title="Select the pages">
    Select pages in the page rail to export that selection. With no page selection, Koharu exports the active page.
  </Step>

  <Step title="Choose a format">
    <Tabs>
      <Tab title="PNG">
        A flattened image for delivery and review. It includes translated text, artwork, visibility, opacity, fitting, fill, and stroke from the retained renderer.
      </Tab>

      <Tab title="PSD">
        A layered document for further typography or artwork edits in a compatible editor. It contains the original image, a hidden text-removal mask, one layer per cleanup or paint layer, and editable text layers. The original image layer is hidden when a cleanup layer exists. Per-layer visibility and opacity are not written, although the merged preview honors them. Pages larger than 30000 pixels on a side cannot be exported as PSD.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Choose a destination">
    Select an output directory in the native folder dialog. Filenames use a four-digit counter in the order the pages are exported, followed by the page label:

    ```text theme={null}
    0001_page-name.png
    0002_page-name.png
    ```

    A single page or a Shift-click range follows project order; a Ctrl-click selection follows click order. Characters that are invalid in filenames become underscores, and everything after the last dot in a label is dropped, so `vol.1` becomes `vol`. Existing files in the directory are overwritten.
  </Step>
</Steps>

<Note>
  PSD is an interchange format. It does not preserve all OCR semantics, model provenance, revision
  history, or renderer behavior as native Photoshop concepts. Keep the `.khrproj` directory as your
  editable source and backup.
</Note>

## Check consistency

Canvas, PNG, and PSD begin with the same scene and prepared rendering result. If they differ, report the project revision, page, format, and images through [troubleshooting](/en/reference/troubleshooting).

There is no separate “inpainted image only” export.


# Process pages
Source: https://koharu.rs/en/guides/processing

Run detection, OCR, translation, and inpainting at the scope your edit needs.

The processing selector above the canvas controls the page scope and stages. Start with the smallest scope that covers the work.

## Choose a scope

<Tabs>
  <Tab title="Current page">Process the page currently shown on the canvas.</Tab>
  <Tab title="Selected pages">Process the pages selected in the page rail.</Tab>
  <Tab title="Entire project">Process every page in project order.</Tab>

  <Tab title="Selected layers">
    Choose **Process → Process Selected Layers** after editing or adding a few text elements. It
    runs OCR and translation on the selected layers only.
  </Tab>
</Tabs>

## Choose stages

Select any non-empty set of stages, then choose **Run**. Selected stages follow this dependency order:

```mermaid theme={null}
flowchart LR
  detection["Detection"] --> ocr["OCR"] --> translation["Translation"]
  detection --> inpainting["Inpainting"]
```

Detection creates regions and removal masks. OCR reads those regions. Translation writes target text. Inpainting reconstructs artwork under the lettering.

<Note>
  Omitted prerequisites are not added automatically. Include detection or OCR when a later stage
  needs fresh input. **Run Inpainting** means detection plus inpainting; it does not include OCR or
  translation.
</Note>

The **Process** menu also offers **Process Project**, **Process Selected Pages**, and **Run Detection**, **Run OCR**, **Run Translation**, and **Run Inpainting**. A **Run** item runs every stage up to the named one and always covers the entire project, regardless of the scope selector.

## Follow progress and stop work

Only one processing job runs at a time, and pages cannot be imported while one is running. The activity center shows the stage, model, progress, and failures.

Each stage commits when it finishes. Completed work remains available if a later stage fails. Stopping prevents new work from starting; a native call already in progress returns at a safe boundary. Its result is discarded if stop was requested before the commit.

Stages with no applicable input complete without inference, although the model is still loaded first. A page with no detected text does not need OCR or translation.

<Warning>
  Rerunning a stage does not discard your edits. Detection skips any page that already has a text
  region, so delete the existing regions to detect a page again. OCR and translation replace
  generated text but keep source text and translations you edited. Inpainting skips a page that
  already has a cleanup layer unless you paint a new **Remove** mask.
</Warning>

Continue with [text review](/en/guides/review) or [cleanup](/en/guides/cleanup).


# Projects and imports
Source: https://koharu.rs/en/guides/projects

Keep pages, translations, and artwork together in a portable Koharu project.

A project owns its source images, analysis, text, artwork edits, and presentation. Koharu saves your work in a `.khrproj` directory; it does not overwrite imported files.

## Create and reopen projects

The start screen lists projects under your operating system's Documents directory:

```text theme={null}
Documents/
  Koharu/
    My Project.khrproj/
```

Create, open, or delete projects here. Names must not contain path separators or characters reserved by the operating system. Close the open project to return to the library.

<Warning>
  Deleting a project permanently removes its entire directory. Session undo cannot restore it.
</Warning>

## Import pages

<Steps>
  <Step title="Choose files or a folder">
    Open **File → Import Pages → Files** to select images, archives, or PDFs. Choose **Folder** to
    scan a directory recursively. Wait for any processing job to finish before importing.
  </Step>

  <Step title="Check the imported order">
    Image paths and archive entries use alphanumeric ordering: `page2.png` comes before
    `page10.png`. PDF pages retain document order. Folder import skips unsupported files and does
    not follow symbolic links.
  </Step>

  <Step title="Organize the page rail">
    Select pages or a range, rename labels, drag pages into order, or delete pages. Deletion has no
    confirmation dialog but can be undone. Page order determines processing order.
  </Step>
</Steps>

| Source | Imported result |
| - | - |
| PNG, JPEG (`.jpg`, `.jpeg`), WebP | One project page per image |
| CBZ, ZIP, RAR | One page per PNG, JPEG, or WebP entry; nested archives and PDFs are skipped |
| PDF | One PNG rendered at 300 DPI per document page |

Only the `.rar` extension is recognized for RAR archives; rename a `.cbr` file before importing it. Imported bytes are copied into content-addressed project storage. Moving or deleting an original source does not remove the imported page.

## Back up and restore

Close the project, then copy the **entire** `.khrproj` directory. Both state files and blobs are required. To restore it, close Koharu and put the complete directory under `Documents/Koharu`.

<Note>
  Closing a project preserves its latest saved state but clears session undo and redo history. An
  open project holds an exclusive lock, so the same project cannot be opened twice.
</Note>


# Review text and layers
Source: https://koharu.rs/en/guides/review

Correct source text and translation without losing the page's editable structure.

Select a text layer on the canvas or in the inspector. Source analysis, semantic text, and visual layout are separate, so you can correct OCR without rebuilding the text box.

## Correct the text

A text layer holds source text, a translation, typography, writing direction, and either its own frame or an automatic fit to a detected region. Source text and translation are edited in the expanded layer row of the inspector.

Edit **source text** when OCR is wrong. Edit **translation** for meaning, tone, names, or line breaks.

<Note>
  Koharu renders translated text only. A source-only layer does not automatically show its OCR text
  on the canvas or in exports.
</Note>

## Manage layers

The layer view follows the page hierarchy: groups, text, raster layers, and image or artwork layers. The list selects one layer at a time; select several layers on the canvas with a modifier click or **Edit → Select All Layers**. Use the arrow buttons to reorder a layer among its siblings, toggle visibility, change opacity, and delete a layer with its descendants.

Analysis regions describe model findings. They are not visible presentation layers and do not compete with artwork or text during selection.

## Review a page

<Steps>
  <Step title="Check detection and OCR">
    Verify the text regions, then correct source recognition errors.
  </Step>

  <Step title="Review the translation">
    Check meaning, tone, terminology, and names against the source.
  </Step>

  <Step title="Inspect the artwork">
    Look for remnants of source lettering and damage around cleanup regions.
  </Step>

  <Step title="Check the reading experience">
    Adjust typography and fitting, then inspect the composite at normal reading size.
  </Step>
</Steps>

## Undo and redo

Use **Edit → Undo** or **Redo**. The defaults are `Ctrl+Z` and `Ctrl+Shift+Z` on Windows/Linux, or `Command+Z` and `Command+Shift+Z` on macOS.

Each page-stage result that the pipeline commits is its own undo step, so undoing a project run takes one step per page and stage. Closing and reopening a project loads the saved state without restoring the previous undo stack.


# Typeset a translation
Source: https://koharu.rs/en/guides/typesetting

Fit text with suitable fonts, writing direction, alignment, fill, and stroke.

Typography is saved in the scene. The canvas and exports use the same page presentation.

<Steps>
  <Step title="Choose a text frame">
    Use a detected text or bubble region for automatic fitting, or create point text or a paragraph frame with **Text**.

    A text layer without authored geometry can derive its frame from a fit region. Manually transforming it gives the layer its own geometry.
  </Step>

  <Step title="Choose fonts with the right coverage">
    The font picker includes bundled and discovered system fonts. If a face lacks a glyph, Koharu tries the ordered default stack in **Settings → Typesetting**, then system fallback.

    Use fonts that cover the target script. A Latin display font alone is insufficient for Japanese or Chinese dialogue.
  </Step>

  <Step title="Fit and style the text">
    Set family, weight, style, size or automatic fitting, writing mode, alignment, fill, and stroke. Typography changes apply to every selected text layer. Visibility and opacity also affect the result.

    Automatic fitting keeps the text inside its presentation frame. Disable it for a fixed size; reset fitting after a substantial translation edit.
  </Step>

  <Step title="Review at reading size">
    Check every page using the visibility and opacity you intend to export. Confirm the translation is present: source OCR is never rendered as fallback text.
  </Step>
</Steps>

## Vertical CJK text

Vertical writing uses shaping and OpenType features rather than a rotated horizontal line. Columns follow the writing direction; supported fonts supply vertical punctuation forms.

Inspect punctuation, emphasis marks, Latin runs, and small kana individually. Font coverage, vertical metrics, and translation length still determine the quality of the result.

<Tip>
  Use [PNG for delivery or PSD for layered editing](/en/guides/export), and retain the Koharu
  project for future changes to semantic text and fitting.
</Tip>


# Hardware and runtimes
Source: https://koharu.rs/en/hardware

Choose a usable device and understand what Koharu downloads and caches.

Koharu downloads the native libraries and model files needed by the features you use. You do not need a full CUDA or ROCm SDK installation to run a release.

## Device selection

Startup chooses a shared ML device from the available backends: Metal on Apple silicon, then CUDA, ROCm/HIP, Vulkan, or CPU where supported. A device is selected only when the Torch, llama.cpp, and diffusion runtimes all publish a package for it, so the operating system, driver, and model backend must all support the selected path.

<Tabs>
  <Tab title="NVIDIA">
    CUDA 13.3 support is available on Windows and Linux. Koharu selects a CUDA device only when the
    driver reports CUDA 13.3 or newer and the GPU has compute capability 7.5 or newer, which means a
    Turing-class or newer GPU with an R610-series or newer driver. See NVIDIA's [driver and
    architecture
    matrix](https://docs.nvidia.com/datacenter/tesla/drivers/cuda-toolkit-driver-and-architecture-matrix.html)
    and [driver downloads](https://www.nvidia.com/en-us/drivers/).
  </Tab>

  <Tab title="AMD">
    ROCm/HIP support depends on the exact GPU, operating system, and driver. Install a compatible
    [AMD driver](https://www.amd.com/en/support). Koharu resolves its required ROCm runtime packages
    automatically. Check AMD's [compatibility
    matrix](https://rocm.docs.amd.com/en/docs-10.0.0/compatibility/compatibility-matrix.html) for
    platform requirements.
  </Tab>

  <Tab title="Apple silicon">
    Koharu uses Metal for supported local inference on Apple-silicon macOS.
  </Tab>

  <Tab title="Vulkan and CPU">
    Vulkan provides an accelerator option on Windows and Linux for llama.cpp and diffusion models,
    such as local translation, PaddleOCR-VL, FLUX.2 Klein, and RORem. Torch has no Vulkan build, so
    detection, the other OCR models, LaMa, and AOT run on CPU on a Vulkan-only machine. If no
    complete accelerator path initializes, Koharu falls back to CPU. CPU inference requires no GPU
    SDK and is slower.
  </Tab>
</Tabs>

<Note>
  The editor canvas uses WebGPU in the embedded CEF webview. It still needs a working WebGPU adapter
  and graphics driver when ML inference runs on CPU.
</Note>

## Downloads and caches

| Data | When it is needed |
| - | - |
| Torch, llama.cpp, diffusion, and backend runtime packages | When their runtime is initialized |
| Pinned or versioned model weights | On first use of the selected processor |
| Local GGUF quantizations | When you choose and use that model file |

On macOS and Linux, packages live under the operating system cache directory in `koharu/packages`. On Windows, they live in the `store` directory inside Koharu's installation directory. Projects live under `Documents/Koharu`; settings live in `~/.koharu/config.toml`. See [data locations](/en/reference/data).

Downloads are staged before being published to the cache. Retry an interrupted download on the next launch or model use.

## Memory and model residency

The resource monitor in the page rail footer reports process and system memory, CPU usage, and the selected device's utilization and memory. Models load on first use and stay loaded for later stages. If a stage fails with an out-of-memory error, Koharu unloads the other stages' models and retries that stage once. Saving settings unloads models, so the next run reloads them.

Start with a moderate local quantization. Smaller files usually need less memory, with a possible quality trade-off. A model that fits on disk can still exceed device memory.

If startup fails, check network access to the package repositories, update the driver, and retry once. Capture the full error if it repeats and follow [troubleshooting](/en/reference/troubleshooting).


# Koharu documentation
Source: https://koharu.rs/en/index

Everything you need to translate, edit, and export manga with Koharu.

<div>
  <div>
    <img alt="" />

    <h1>Koharu documentation</h1>

    <div>
      <a href="https://github.com/koharu-rs/koharu" aria-label="GitHub">
        <Icon icon="github" />
      </a>

      <a href="https://discord.gg/mHvHkxGnUY" aria-label="Discord">
        <Icon icon="discord" />
      </a>

      <a href="https://x.com/mayo_irl" aria-label="X">
        <Icon icon="x-twitter" />
      </a>
    </div>

    <p>An editable manga translation workflow, from your first page to the final export.</p>
  </div>

  <section>
    <h2>Get started</h2>

    <CardGroup>
      <Card title="Install Koharu" icon="download" href="/en/installation">
        Download a release for Windows, macOS, or Linux.
      </Card>

      <Card title="Your first translation" icon="rocket" href="/en/quickstart">
        Translate one page, review it, and export the result.
      </Card>

      <Card title="Hardware and runtimes" icon="microchip" href="/en/hardware">
        Check device support and how models are downloaded.
      </Card>
    </CardGroup>
  </section>

  <section>
    <h2>Work with pages</h2>

    <CardGroup>
      <Card title="Projects and imports" icon="folder-open" href="/en/guides/projects">
        Bring images, archives, and PDFs into one project.
      </Card>

      <Card title="Process pages" icon="play" href="/en/guides/processing">
        Choose the pages and stages you want to run.
      </Card>

      <Card title="Review text" icon="spell-check" href="/en/guides/review">
        Correct OCR, wording, names, and line breaks.
      </Card>

      <Card title="Clean up artwork" icon="eraser" href="/en/guides/cleanup">
        Remove source lettering and repair the image.
      </Card>

      <Card title="Typeset translations" icon="font" href="/en/guides/typesetting">
        Fit text with fonts, alignment, fill, and stroke.
      </Card>

      <Card title="Export PNG and PSD" icon="file-export" href="/en/guides/export">
        Deliver flattened images or editable layered files.
      </Card>
    </CardGroup>
  </section>

  <section>
    <h2>Models and providers</h2>

    <CardGroup>
      <Card title="Vision and inpainting" icon="eye" href="/en/models/vision">
        Choose detection, OCR, and image-repair models.
      </Card>

      <Card title="Translation providers" icon="plug" href="/en/models/providers">
        Connect local models or hosted translation services.
      </Card>

      <Card title="Translation settings" icon="language" href="/en/models/translation">
        Set language, instructions, and generation options.
      </Card>
    </CardGroup>
  </section>

  <section>
    <h2>Koharu Agent</h2>

    <CardGroup>
      <Card title="Set up the Agent" icon="robot" href="/en/agent/setup">
        Sign in and choose the model for project assistance.
      </Card>

      <Card title="Work with a project" icon="comment" href="/en/agent/projects">
        Ask the Agent to inspect pages and make scoped edits.
      </Card>
    </CardGroup>
  </section>

  <section>
    <h2>Developers</h2>

    <CardGroup>
      <Card title="Build Koharu" icon="terminal" href="/en/development/setup">
        Set up a checkout and run the desktop application.
      </Card>

      <Card title="Architecture" icon="sitemap" href="/en/development/architecture">
        Follow ownership across the UI, scene, and runtimes.
      </Card>

      <Card title="Contribute" icon="code-pull-request" href="/en/development/contributing">
        Prepare a focused change and a clear pull request.
      </Card>
    </CardGroup>
  </section>

  <section>
    <h2>Get help</h2>

    <CardGroup>
      <Card title="Troubleshooting" icon="circle-question" href="/en/reference/troubleshooting">
        Diagnose problems and collect useful logs.
      </Card>

      <Card title="Settings" icon="gear" href="/en/reference/settings">
        Find the controls for your workflow.
      </Card>

      <Card title="Keyboard shortcuts" icon="keyboard" href="/en/reference/shortcuts">
        Navigate and edit with the default tool bindings.
      </Card>
    </CardGroup>
  </section>

  <section>
    <h2>About Koharu</h2>

    Koharu keeps source text, translations, artwork, and layout together in a local project. Run a complete translation pipeline or revise an individual stage, then use the [canvas tools](/en/guides/canvas) to finish the page.

    <Frame>
      <img alt="Koharu displaying a translated manga page, with a page list on the left and typography and layers on the right." />
    </Frame>

    <p>Projects stay on your machine. Hosted translation or generation providers receive the content needed for the requests you send.</p>
  </section>
</div>


# Install Koharu
Source: https://koharu.rs/en/installation

Download a release, complete the first launch, and keep the app up to date.

<Steps>
  <Step title="Choose a release">
    Open the [latest GitHub release](https://github.com/koharu-rs/koharu/releases/latest) and select the package for your operating system and processor.

    <Tabs>
      <Tab title="Windows">
        Run the Windows installer from the release, or install with WinGet:

        ```powershell theme={null}
        winget install koharu
        ```
      </Tab>

      <Tab title="macOS">
        Choose the Apple-silicon release and place Koharu in Applications, or install with Homebrew:

        ```bash theme={null}
        brew install --cask koharu
        ```
      </Tab>

      <Tab title="Linux">
        Choose the package for your distribution and processor. Install any desktop-library dependencies reported by your package manager.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Let the runtime initialize">
    Launch Koharu and wait for the project browser. First launch can take longer while native packages download. Model files download when you first use the selected model.

    Runtime packages come from GitHub release assets, PyPI for CUDA, and AMD's repository for ROCm; model weights come from Hugging Face. Keep the app open while downloads finish; the activity center shows progress.
  </Step>

  <Step title="Create your first project">
    Follow the [quickstart](/en/quickstart) with one readable manga page. Check [hardware and runtimes](/en/hardware) if device initialization fails.
  </Step>
</Steps>

## Install updates

Release builds check a signed GitHub release feed once at startup; there is no manual update check. When an update is offered, let the download complete before Koharu relaunches.

<Tip>
  Use a release build for translation work. Use the [development setup](/en/development/setup) when
  you want to change Koharu's code.
</Tip>


# Connect a translation provider
Source: https://koharu.rs/en/models/providers

Use local GGUF models, hosted services, or a compatible model server.

The translation picker combines local and hosted backends. A selection records the provider, model ID, optional local quantization, and vision-input setting.

## Available connections

| Connection | Providers |
| - | - |
| Local inference | GGUF models through llama.cpp |
| Hosted models | OpenAI, Gemini, Claude, Grok, MiniMax, DeepSeek, OpenRouter |
| Compatible servers | LM Studio and OpenAI-compatible endpoints |
| Machine translation | DeepL, Google Cloud Translation, Caiyun |

Each provider owns its endpoint defaults, request mapping, and model discovery. Available models can change independently of these docs.

<Steps>
  <Step title="Save the connection">
    Open **Settings → Providers**, choose a provider, and fill in its fields. Hosted services
    require credentials. A local compatible server needs its base URL; LM Studio defaults to
    `http://localhost:1234` and OpenAI-compatible defaults to `http://localhost:11434/v1`. Whether a
    local server needs a secret depends on that server.
  </Step>

  <Step title="Select a model">
    Open the processing selector or **Settings → Translation**. Opening the processing selector, or
    the Settings page, refreshes provider discovery. An unreachable provider may have no discovered
    models even while its saved settings remain intact.
  </Step>

  <Step title="Choose whether to include the page image">
    **Vision** is on by default and the switch stays available for every model. If the selected
    model does not accept images, Koharu drops the image from the request. OpenAI-compatible
    endpoints are assumed to accept images, so turn the switch off when the server cannot handle
    image messages.
  </Step>

  <Step title="Try one page">
    Check the source OCR, run translation on the current page, and review the response before
    processing a chapter.
  </Step>
</Steps>

## Credentials and privacy

Provider secrets use the operating system's secure credential service. Non-secret endpoint settings live in `~/.koharu/config.toml`.

Local models keep prompts and text on your machine after download. Hosted providers receive request content and apply their own retention terms. Local detection and OCR do not make a hosted translation request local.

<Warning>
  Keep keys out of project instructions, text layers, and configuration files. Save credentials
  through **Settings → Providers**.
</Warning>


# Configure translation
Source: https://koharu.rs/en/models/translation

Set language, instructions, quantization, sampling, and image input.

Choose output settings in the processing selector or **Settings → Translation**. Koharu captures them when a run starts; edits affect later runs. Provider connections and credentials are read for each request.

## Language and instructions

Set the target language and concise instructions for names, terminology, tone, pronouns, formatting, or text that should remain untranslated. Instructions are saved with Koharu's settings and apply to every project; there is no per-project field. Test them on several pages and correct OCR first.

LFM 2.5 and Ministral 3 support a limited set of target languages, and a run fails when their target is unsupported. Other local models accept every target language Koharu offers.

## Local quantization

GGUF models may offer multiple quantizations. Smaller files need less download space and memory, usually at a quality cost. Larger files can be slower or exceed available memory. Hosted providers control their own serving precision.

## Generation controls

| Control | What to adjust |
| - | - |
| Temperature, top P, top K, min P | Sampling and randomness |
| Repeat, frequency, presence penalties | Repetition behavior |
| Maximum output tokens | Response length budget |
| Reasoning | Additional reasoning for supported models |
| Vision | Whether a supported model receives the source page image |

<Tip>
  Start with provider defaults and change one variable at a time. High randomness tends to make
  names and terminology less consistent.
</Tip>

Reasoning can increase latency and token use. Reasoning and vision are dropped silently for a model that does not support them; other unsupported options may be ignored or rejected by a provider or model.

## Text and vision inputs

Text-only requests send semantic source text. With **Vision**, a capable model also receives the source page image. A custom OpenAI-compatible server is assumed to accept images, so turn **Vision** off if it does not support image messages.

Generated translations remain editable project data. [Review the wording and page layout](/en/guides/review) before export.


# Vision and inpainting models
Source: https://koharu.rs/en/models/vision

Choose processors for detection, OCR, and artwork reconstruction.

Open **Settings → Pipeline** and choose a model for each stage. Models own their preprocessing and options; the [workflow](/en/guides/processing) stays the same.

## Detection

**Koharu Layout RF-DETR Seg 2XL** detects text, speech bubbles, and panels, and produces segmentation data for later stages.

Text, bubble, and panel thresholds control how much evidence each class needs. Lower thresholds retain more uncertain regions and may increase false positives. Compare several representative pages before changing thresholds. Detection skips a page that already has text regions, so delete them to detect the page again with new thresholds.

## OCR

| Processor | Use |
| - | - |
| PaddleOCR-VL 1.6 | Default general vision-language OCR |
| Manga OCR | Japanese manga text |
| Baberu OCR | Alternative manga-oriented recognition |
| Hayai OCR | Chinese, Korean, Japanese, and English manga text |

<Note>
  OCR reads detected text regions. Check detection first when text is missing: changing the
  recognizer cannot recover a region that was never passed to it.
</Note>

## Inpainting

<Tabs>
  <Tab title="Direct">
    **LaMa** is the default. **AOT Inpainting** is another direct reconstruction model. Start here for routine lettering removal.
  </Tab>

  <Tab title="Generative">
    **FLUX.2 Klein** accepts a reconstruction prompt. **RORem Mixed** is manga-focused and exposes positive and negative prompts.

    These choices generally need more runtime data, memory, and time. Describe surrounding artwork and the removal of letters; typeset the translation with text layers.
  </Tab>
</Tabs>

## Profiles and first runs

Supported processors keep independent settings profiles. Returning to a generative model restores its prompt fields instead of inheriting another model's options.

Models load on demand and stay loaded until settings are saved or an out-of-memory retry unloads them. A first run includes download and loading costs, so compare warmed models on identical pages before selecting a project default.


# Translate your first page
Source: https://koharu.rs/en/quickstart

Create a project, run the pipeline, review the page, and export PNG or PSD.

Start with one readable PNG, JPEG, or WebP manga page and an [installed copy of Koharu](/en/installation).

<Steps>
  <Step title="Create a project">
    On the start screen, enter a name in **New project** and choose **Create**. Koharu creates a self-contained `.khrproj` directory under `Documents/Koharu` and opens the editor.
  </Step>

  <Step title="Import your page">
    Choose **File → Import Pages → Files**, or use the **Import** button shown in the empty page rail. Select your image. Koharu copies it into the project, so you can move the original later.
  </Step>

  <Step title="Choose the translation output">
    Open the processing selector above the canvas. Select a translation model, target language, and any instructions. Instructions are saved with Koharu's settings and apply to every project.

    For a hosted model, first save its connection in **Settings → Providers**. See [translation providers](/en/models/providers).
  </Step>

  <Step title="Run the pipeline">
    Choose **Current page**, select all four stages, and click **Run**.

    Detection finds text, bubbles, and panels. OCR reads the detected text, translation writes the target-language text, and inpainting removes source lettering. Translation needs OCR; inpainting can proceed from detection.

    Follow the current page, stage, and model in the activity center.
  </Step>

  <Step title="Review the result">
    Select a text layer and compare source text with its translation in the inspector. Correct OCR, wording, names, and line breaks.

    Paint over missed source lettering with **Remove**; releasing the stroke runs inpainting on that area right away. Use **Brush** or **Eraser** for raster touch-ups and **Text** for a missing text box. Undo an unwanted edit.
  </Step>

  <Step title="Fit the text">
    Adjust the font, size, automatic fitting, alignment, writing direction, fill, and stroke. Check the page at normal reading size.

    <Note>
      Only translated text is rendered. Source OCR stays editable, but it does not appear as fallback text when a translation is empty.
    </Note>
  </Step>

  <Step title="Export">
    Choose **File → Export PNG** for a flattened image or **File → Export PSD** for a layered document. Select an output directory.
  </Step>
</Steps>

<CardGroup>
  <Card title="Process a chapter" icon="layers" href="/en/guides/processing">
    Choose page scopes and rerun only the stages that need work.
  </Card>

  <Card title="Refine the artwork" icon="paintbrush" href="/en/guides/cleanup">
    Use precise removal masks and manual raster corrections.
  </Card>
</CardGroup>


# Formats and data
Source: https://koharu.rs/en/reference/data

Locate projects, non-secret settings, credentials, and replaceable caches.

## Supported formats

| Purpose | Format |
| - | - |
| Import | PNG, JPEG, WebP, CBZ, ZIP, RAR, PDF |
| Flattened export | PNG |
| Layered interchange | PSD |
| Working project | `.khrproj` directory |

## Project data

Projects live at `Documents/Koharu/<project-name>.khrproj/`. Each contains alternating durable state files, a lock file while the project is open, and content-addressed blobs for source images, generated artwork, and authored raster edits. Unreferenced blobs are not removed automatically, so a heavily edited project can grow over time.

<Warning>
  Do not change internal project files while the project is open. Deletion from the project browser
  permanently removes the complete directory.
</Warning>

## Settings and credentials

Non-secret typed settings live in `~/.koharu/config.toml`, with sections for the pipeline (including translation), providers, typesetting, Agent, and HTTP timeouts. Missing settings use defaults. Invalid manual edits can prevent initialization; use the Settings UI.

Provider credentials use the operating system's secure credential service. A project backup does not include provider keys or the Agent account session.

## Runtime and model cache

On macOS and Linux, packages are stored at `<cache>/koharu/packages/` under the operating system cache directory. On Windows, they are stored in the `store` directory inside Koharu's installation directory. This data is replaceable: removing it while Koharu is closed causes the required packages to download again.

Never remove a package while the desktop process may still have a native library loaded.

## Back up safely

<Steps>
  <Step title="Close the project">Finish current work before copying its files.</Step>

  <Step title="Copy the entire directory">
    Keep the state files and blobs together. A PSD export is not a project backup.
  </Step>

  <Step title="Save settings separately">
    Copy `config.toml` if needed. Reconfigure credentials through Koharu on the restored machine.
  </Step>
</Steps>


# Settings
Source: https://koharu.rs/en/reference/settings

Find the controls for appearance, processors, providers, translation, and fonts.

Open **File → Settings** or the settings button on the project screen. Pipeline, provider, translation, and typesetting changes save automatically after a short delay.

## Appearance

Choose **Light**, **Dark**, or **System**, and the desktop interface language. These settings do not change page rendering or the translation target language.

## Pipeline

Choose detection, OCR, and inpainting processors. The selected processor exposes its own options, such as class thresholds or generative prompts. Processor profiles are retained independently. Saving pipeline settings unloads any loaded model.

## Providers

Configure a connection listed in [translation providers](/en/models/providers). Credentials use the operating system credential service; URLs and other non-secret options use the shared configuration. Provider changes refresh model discovery.

## Translation

Choose the provider and model, local quantization, target language, and instructions. Generation controls include sampling, repetition penalties, maximum tokens, reasoning, and image input.

The canvas processing selector exposes the frequently changed model and output fields. See [translation settings](/en/models/translation) for their effects.

## Typesetting

Set the ordered default font-family stack. Koharu tries these families when a preferred family cannot supply usable glyphs, then uses system fallback. Individual text layers still own their typography.

## Shortcuts

Assign one character to Select, Text, Brush, Eraser, Color picker, Remove, Pan, and Fit Window. Custom tool bindings apply to the running session only; they are not saved and reset to the defaults when Koharu restarts.

<Note>
  Pipeline, provider, typesetting, Agent, and HTTP timeout configuration live in
  `~/.koharu/config.toml`; translation settings are part of the pipeline section. Keep credentials
  separate and use the Settings UI instead of hand-editing secrets into the file.
</Note>

See [data locations](/en/reference/data) for project and cache storage.


# Keyboard shortcuts
Source: https://koharu.rs/en/reference/shortcuts

Default tools, navigation gestures, selection, and undo commands.

Tool and editing shortcuts apply while a project is open and an input, textarea, or editable text region is not focused.

## Tools

| Tool | Key |
| - | - |
| Select | `V` |
| Text | `T` |
| Brush | `B` |
| Eraser | `E` |
| Color picker | `I` |
| Remove | `J` |
| Pan | `H` |
| Fit Window | `0` |

Change tool characters in **Settings → Shortcuts**.

## Navigation

| Action | Gesture |
| - | - |
| Pan temporarily | Hold `Space` or the middle button and drag |
| Pan | Scroll; `Shift` + scroll pans horizontally |
| Zoom at the pointer | `Ctrl` + scroll |
| Change brush diameter | `Alt` + scroll with Brush, Eraser, or Remove |
| Cancel gesture and clear selection | `Escape` |
| Fit the active page | `0` by default |

The active tool does not change while `Space` is held. Switching away from Koharu cancels an unfinished canvas gesture.

## Editing

| Action | Windows / Linux | macOS |
| - | - | - |
| Undo | `Ctrl+Z` | `Command+Z` |
| Redo | `Ctrl+Shift+Z` | `Command+Shift+Z` |
| Select all editable page layers | `Ctrl+A` | `Command+A` |
| Delete selected layers | `Delete` or `Backspace` | `Delete` or `Backspace` |

<Tip>
  Use a unique character for each tool. If bindings conflict, the Fit Window key is checked first,
  then the first matching tool in toolbar order wins. Custom bindings reset when Koharu restarts.
</Tip>

Shortcuts affect the desktop interface, not the exported page.


# Troubleshooting
Source: https://koharu.rs/en/reference/troubleshooting

Diagnose a problem and collect the information needed to reproduce it.

Start with the complete error in the startup view, activity center, or dialog. Identify the failing stage before changing project files or caches.

<AccordionGroup>
  <Accordion title="Koharu does not finish starting">
    First launch can download native packages before the project browser becomes interactive. Let active downloads finish and confirm the repositories are reachable.

    If initialization fails repeatedly, close every Koharu process, update the GPU driver, restart the computer, and retry on a stable network. Capture the complete error.

    Do not remove a runtime directory while a process may have its libraries loaded.
  </Accordion>

  <Accordion title="A model download fails">
    Check access to the model's Hugging Face repository and available cache disk space. Proxies, regional filtering, authentication, antivirus scanning, or interrupted writes can block downloads.

    Retry the same model once. If the same file fails, include the repository, filename, and full error in your report.
  </Accordion>

  <Accordion title="Inference falls back to CPU">
    A detected GPU still needs a compatible driver, backend, and runtime package. Check the resource
    monitor and startup logs for the device actually selected. CPU fallback is expected when no
    complete accelerator path is usable, and Torch-based models such as detection, most OCR models,
    LaMa, and AOT always run on CPU when only Vulkan is available. See [hardware](/en/hardware).
  </Accordion>

  <Accordion title="Detection or OCR misses text">
    Check that the page is upright and readable. Inspect detected regions before changing OCR models.
    Detection does not run again on a page that already has text regions, so delete them before
    rerunning it. Adjust thresholds conservatively across several pages, try a manga-specific
    recognizer for Japanese, and correct source text before translating again.
  </Accordion>

  <Accordion title="Inpainting damages artwork">
    Paint a smaller Remove mask and avoid bubble borders and line art. Try a direct inpainting model
    before a heavier generative model. Clear the layer selection before painting so touch-ups go to a
    separate Paint layer instead of the cleanup layer.
  </Accordion>

  <Accordion title="A translation provider fails">
    Verify credentials, base URL, and provider-specific fields in **Settings → Providers**, then
    reopen the processing selector. For a compatible server, check the chat endpoint and turn
    **Vision** off if the selected model does not accept images.
  </Accordion>

  <Accordion title="Koharu Agent cannot sign in or run">
    Cancel the existing sign-in or request before retrying. Check that browser authorization completed
    for the intended ChatGPT account. Agent sign-in is separate from OpenAI translation-provider
    credentials.
  </Accordion>

  <Accordion title="Text is missing or malformed">
    Confirm the layer contains translated text, is visible, has nonzero opacity, and uses a font
    covering the target script. Reset automatic fitting after large text changes. Source-only text is
    not rendered.
  </Accordion>

  <Accordion title="Export differs from the canvas">
    Capture the project revision, affected page, format, canvas screenshot, and exported image. Canvas and exports start from the same prepared frame, so a meaningful mismatch should be reported.
  </Accordion>
</AccordionGroup>

## Collect detailed logs

Start Koharu from a terminal to enable logging for that process. A terminal runs commands you type or paste; leave it open while reproducing the problem.

<Warning>
  Save your work and close every Koharu window first. Logging applies only to the newly launched
  process.
</Warning>

<Tabs>
  <Tab title="Windows">
    <Steps>
      <Step title="Open PowerShell">
        Open Start, search for **PowerShell**, and launch **Windows PowerShell**. Windows Terminal also works with a PowerShell tab. Use PowerShell rather than Command Prompt.
      </Step>

      <Step title="Start Koharu">
        Paste the command with `Ctrl+V` or right-click, then press Enter. Do not paste the `PS C:\Users\YourName>` prompt.

        ```powershell theme={null}
        $env:RUST_LOG="debug"; koharu.exe
        ```
      </Step>

      <Step title="Use a full path if needed">
        If `koharu.exe` is not recognized, search for Koharu in Start, right-click **Open file location**, then open the shortcut's **Properties** and copy **Target**. Replace the example below with that path, keeping `&` and the quotes.

        ```powershell theme={null}
        $env:RUST_LOG="debug"; & "C:\path\to\koharu.exe"
        ```
      </Step>
    </Steps>

    The environment setting lasts only in this PowerShell window. Closing it clears the setting.
  </Tab>

  <Tab title="macOS">
    Press `Command+Space`, search for **Terminal**, and press Return. Paste with `Command+V`, then press Return:

    ```bash theme={null}
    RUST_LOG=debug koharu
    ```

    If the command is not found, launch the app from its installed path:

    ```bash theme={null}
    RUST_LOG=debug /Applications/koharu.app/Contents/MacOS/koharu
    ```

    If that path does not exist, check the app's location in Finder and substitute its actual path.
  </Tab>

  <Tab title="Linux">
    Search the application menu for **Terminal**, or try `Ctrl+Alt+T`. Paste with `Ctrl+Shift+V`, then press Enter:

    ```bash theme={null}
    RUST_LOG=debug koharu
    ```

    If the command is not found, try the Debian/RPM package location:

    ```bash theme={null}
    RUST_LOG=debug /usr/bin/koharu
    ```

    If that file is missing, check or reinstall the package for your distribution.
  </Tab>
</Tabs>

Reproduce the problem with this copy of Koharu. The terminal may remain busy until the app closes; keep the complete surrounding output, not just the last error. Close Koharu normally afterward, or press `Ctrl+C` once in the terminal if the launched process is frozen.

## Save a log file

In a new terminal, run the command for your platform, reproduce the problem, and close Koharu. The log is written to your home directory. Substitute the full executable path if the short command was unavailable.

<Tabs>
  <Tab title="Windows">
    ```powershell theme={null}
    $env:RUST_LOG="debug"; koharu.exe *>&1 | Tee-Object -FilePath "$HOME\koharu-debug.log"
    ```
  </Tab>

  <Tab title="macOS and Linux">
    ```bash theme={null}
    RUST_LOG=debug koharu 2>&1 | tee "$HOME/koharu-debug.log"
    ```
  </Tab>
</Tabs>

Before sharing, replace credentials, private filenames, and private page text with `[removed]`, keeping surrounding diagnostics. Include your OS, Koharu version, intended action, reproduction steps, and approximate error time.

Attach the text log to a [GitHub issue](https://github.com/koharu-rs/koharu/issues) or ask on [Discord](https://discord.gg/mHvHkxGnUY).