User Guide

Everything you need to know to get started with Koali and make the most of your qualitative analysis.

Getting Started

Browser requirements

Koali runs entirely in your web browser. For the best experience, use a Chromium-based browser:

Creating a project

1. Open Koali in your browser.
2. On the home screen, enter your display name. This identifies your work in collaborative projects.
3. Click Create New Project.
4. Choose a folder on your computer. Koali will store all project data here as plain JSON files.
5. Give your project a name and optional description.

Opening an existing project

1. Click Open Existing Project on the home screen.
2. Select the folder containing a Koali project (the one with a koali.json file).
3. Koali loads your project, including all sources, codes, notes, and codings.

Recent projects are listed on the home screen for quick access.

Importing Documents

Supported formats

How to import

1. Click the Import button in the left panel.
2. Select one or more files in the file picker. You can select multiple files at once.
3. Koali automatically detects the file type from the extension and parses accordingly.
4. Imported documents appear in the source list on the left panel.

Original files are copied into your project's sources/ folder. Parsed content is cached locally in IndexedDB for fast loading on subsequent opens.

Managing sources

Right-click on any source in the list to:

• Rename — change the document title.
• Edit Metadata — edit the title, description, and add custom key-value attributes (e.g. "Participant Age", "Interview Location").
• Create Group / Add to Group — organise sources into named groups. Groups appear as collapsible sections in the source list.
• Delete — remove the document and all associated coded segments. A confirmation prompt is shown.

A search bar at the top of the source list lets you filter documents by title.

The Workspace

The workspace is divided into three resizable panels:

Left panel — Sources & Notes

Lists all imported documents and project notes. Click a document to open it in the centre panel. Click a note to open the note editor.

Centre panel — Document Viewer

Displays the currently selected document. For transcripts, content is shown as individual cues with timestamps and speaker labels. For PDFs, pages are rendered with page numbers. Select text by clicking and dragging to begin coding.

A search bar lets you find text within the current document. Matches are highlighted and scrolled into view.

Right panel — Codes

Shows your codebook as a hierarchical tree. Each code has a colour dot and a count of coded segments. When text is selected in the document, a selection context area appears showing the selected text and a quick code search field.

Toolbar

The toolbar at the top shows the project name and navigation tabs: Workspace, Queries, Charts, Themes, and IRR. Your display name and sync status are shown on the right.

Status bar

The bar at the bottom shows counts for sources, codes, coded segments, and themes, plus the current save status.

Resizing panels

Drag the dividers between panels to resize them. The divider highlights in green when you hover over it.

Coding

Creating codes

1. Click + New Code in the right panel, or press Ctrl+Shift+C.
2. Enter a code name.
3. Optionally select a description template to pre-fill the description field with a structured prompt:
   • Inductive — Definition, When to use, When not to use, Example.
   • Deductive — Theoretical basis, Definition, Indicators, Example.
   • In Vivo — Participant quote, Meaning in context, Related concepts.
4. The new code appears as a root-level item in the code tree.

Organising codes into hierarchies

• Add a child code — right-click a code and select "Add Child Code".
• Drag and drop — drag a code onto another to make it a child. Drag to the root area to move it back to the top level.
• Click the triangle arrow next to a parent code to expand or collapse its children.

Applying codes to text

1. Select text in the document viewer by clicking and dragging.
2. The selection context panel appears in the right panel showing the selected text.
3. Apply a code by any of these methods:
   • Click a code in the tree.
   • Press a number key 1–9 to apply the corresponding root-level code.
   • Press / to focus the quick search, type to filter, use ↑/↓ to navigate, and press Enter to apply. Codes are sorted by usage frequency.

Applied codes appear as coloured highlights on the text. Hover over a highlight to see the code name. Right-click a highlight to see a popover with the code name and a preview of the coded text, with an option to remove the code from that segment.

Editing and deleting codes

• Double-click a code to edit its name and description.
• Right-click a code to access the context menu: edit, delete, add child, or merge.
• Deleting a code removes all associated coded segments. A confirmation is required.

Merging codes

1. Right-click a code and select Merge Into...
2. Select the target code.
3. All segments from the source code are reassigned to the target. The source code is removed.

Exporting the codebook

Right-click any code to access export options:

• Export Codebook (CSV) — download a CSV file containing all codes with their names, descriptions, colours, parent codes, and creation dates.
• Export Codebook (PDF) — generate a printable PDF of your codebook.

Notes

Note types

Creating a note

1. Click + New Note in the left panel, or press Ctrl+Shift+M.
2. Enter a title, select a type, and optionally link the note to a code or document.
3. Add comma-separated tags for organisation.
4. Write your note content using the rich text editor (bold, italic, underline, lists).

Linking notes

Notes can be linked to:

• A code — to annotate a specific code with analytical notes.
• A document — to record observations about a specific source.
• Standalone — not linked to anything, for general project notes.

Queries

Building a query

1. Navigate to the Queries tab.
2. Select one or more codes from the code list (hold Ctrl or Cmd to select multiple).
3. Choose an operator:
   • OR — segments coded with any of the selected codes.
   • AND — segments where all selected codes are applied within the same document.
   • NOT — segments with the first code but not also tagged with other selected codes.
4. Optionally filter to a specific document or leave as "All documents".
5. Click Run Query.

Query results

Results are shown in a table with columns for document title, code (with colour), speaker (for transcripts), and the first 200 characters of coded text. The total result count is shown at the top.

Saving and exporting

• Save Query — name and save query parameters for quick re-use. Saved queries appear as buttons below the search controls.
• Export CSV — download results as a CSV file with document, code, speaker, and text columns.

Visualisations

Navigate to the Charts tab to access visualisations.

Code frequency

A bar chart showing the number of coded segments per code, sorted from most to least frequent. Bar colours match code colours.

Code hierarchy

A tree view showing the parent-child relationships in your codebook. Useful for reviewing codebook structure at a glance.

Code × Document heatmap

A matrix with codes as rows and documents as columns. Cell colour intensity indicates how many times a code was applied in each document. Useful for spotting coding patterns across your dataset.

Word frequency

A word cloud generated from coded text segments. Word size reflects frequency. Common stop words are automatically filtered out, and the top 50 words are displayed. Hover over a word to see its exact count.

Use the Scope dropdown to filter words to a specific code, and the Min freq control to set a minimum occurrence threshold.

Theme visualisations

When you have themes defined, three additional chart types appear:

• Theme Frequency — bar chart of segment counts per theme.
• Theme × Document — heatmap showing theme density across documents.
• Theme Summary — overview cards for each theme showing segment count, document count, associated codes, and codes ranked by frequency.

Heatmap drilldown

Click any cell in the Code × Document heatmap to see the coded text segments for that code-document pair displayed below the matrix.

Exporting charts

When a Chart.js chart is displayed (frequency or heatmap), an Export Chart PNG button appears below the chart to download the current visualisation as a PNG image.

Inter-Rater Reliability

Navigate to the IRR tab to calculate agreement between coders. This requires at least two different users to have coded overlapping segments.

Running an IRR calculation

1. Select Coder 1 and Coder 2 from the dropdown menus.
2. Optionally select a specific document, or analyse all documents.
3. Review the results.

Metrics

Interpreting Cohen's Kappa

A per-code breakdown table shows kappa and agreement for each individual code, helping you identify which codes need clearer definitions. The first 50 disagreements can be reviewed in detail and exported to CSV.

Collaboration

How it works

Koali uses folder-based collaboration. Place your project folder in a shared location such as Dropbox, OneDrive, Google Drive, or a network drive. Each team member opens the same folder in Koali.

Setting up collaboration

1. Create a project and save it to a shared folder.
2. Each team member opens the same folder in Koali using Open Existing Project.
3. Each person sets their own display name and colour in Settings (gear icon) so their work is identifiable.

Team members and roles

In Settings, you can add team members by User ID and assign them a role (Editor or Viewer). The Activity Log in Settings shows a timestamped record of recent project actions.

Backups

Click Backup Project (JSON) in Settings to download a full backup of your project data. You can also click Save All Now to force an immediate save of all unsaved changes.

Conflict detection and resolution

When Koali detects that multiple users have made conflicting changes, a conflict resolution dialog appears. Conflict types include:

• Code renamed — two people renamed the same code differently. Choose one version or enter a custom name.
• Code deleted — one person edited a code while another deleted it. Choose to keep or delete it.
• Note content — two people edited the same note. Choose which version to keep.

Conflicts are shown one at a time. You can resolve them immediately or skip and return later.

Themes

Themes let you group related codes into higher-order patterns, which is a key step in thematic analysis. Navigate to the Themes tab to manage themes.

Creating a theme

1. Click + New Theme.
2. Enter a name (e.g. "Systemic Barriers") and optional description.
3. Choose a colour from the palette.
4. Select which codes belong to this theme using the checkbox list.
5. Click Create Theme.

Managing themes

• Add codes — click the + Add Code button on a theme card, or drag a code from the Workspace codebook tree and drop it onto a theme card.
• Remove codes — click the × button next to a code chip on the theme card.
• Edit or delete — right-click a theme card to edit its name, description, colour, and code associations, or to delete the theme. Deleting a theme does not delete the codes it contains.

Theme badges

In the Workspace codebook tree, codes that belong to a theme display a small coloured badge with the theme name next to the code, so you can see theme associations at a glance.

Keyboard Shortcuts

Data & Privacy

Where data is stored

All project data lives in the folder you chose when creating the project. Nothing is ever uploaded or transmitted. There are no accounts and no sign-in.

Project file structure

Your project folder contains human-readable JSON files:

Because everything is plain JSON, you can inspect, back up, or version-control your project with any standard tool.

Browser caching

Koali uses IndexedDB to cache parsed document content for faster loading. This data stays in your browser and can be cleared at any time through your browser's settings without affecting your project files.

File System Access API

In supported browsers (Chrome, Edge, Opera), Koali uses the File System Access API to read and write directly to your project folder. You grant permission once per session, and the browser may ask you to re-confirm on subsequent visits.

Troubleshooting

Firefox or Safari: no folder picker

These browsers don't support the File System Access API. Koali falls back to a download/upload workflow. You can still use all features, but saving and loading requires manual file operations rather than direct folder access.

Documents not loading

• Check that the file format is supported (PDF, DOCX, TXT, VTT, SRT, or Zoom JSON).
• For PDFs, ensure the file contains selectable text (not scanned images).
• Try clearing your browser's IndexedDB cache and reloading the project.

Sync conflicts on shared folders

• Ensure your cloud sync service has finished syncing before opening the project.
• Avoid having two people work in the same project folder at the same time.
• If conflicts appear, use the conflict resolution dialog to choose the correct version.

Permission prompts

Chrome and Edge may ask you to re-grant folder access each time you open Koali. This is a browser security feature. Click "Allow" or "Edit files" when prompted.

Clearing the cache

If you experience stale data or loading issues, clear the IndexedDB storage for Koali in your browser's developer tools (Application → Storage → IndexedDB). Your project files on disk are not affected.