aktual CLAUDE.md

CLAUDE.md

Guidance for Claude Code when working in this repo.

Project

Aktual is an unofficial Kotlin Multiplatform client for Actual personal budgeting software, targeting Android and Desktop (JVM). Pet project, unaffiliated with upstream.

General

• IMPORTANT: After any architectural/structural change, grep **/CLAUDE.md for references that need updating (scopes, annotations, module paths, DI patterns). Don't wait to be asked.
• Prefer kotlinx.immutable collections in the UI layer, not plain List/Set.
• Prefer stateFlow.update { x } over stateFlow.value = x.
• Strings.xyz (user-facing text) is generated from XML in aktual-core:l10n — add the string there and regenerate, don't hardcode. See aktual-core/l10n.
• In tests, observe Flow/StateFlow emissions with Turbine (flow.test { awaitItem() }), not by reading .value or manual collectors.
• Wrap comments to the max_line_length in .editorconfig (currently 120).

Build commands

# Compile (including test sources) for one module — default choice for module changes
./gradlew :[module]:compileAll

# Compile everything — prefer module-specific form where possible
./gradlew compileAll

# Full build — very slow, don't run without asking
./gradlew build

# Apps
./gradlew :aktual-app:android:assemble
./gradlew :aktual-app:desktop:assemble
./gradlew :aktual-app:android:installDebug
./gradlew :aktual-app:desktop:run

# Tests — always module-specific. `./gradlew allTests` pegs the machine; don't run it.
# Never pass a bare `:module:test` — it's ambiguous for KMP modules. Use `testAll` (both
# targets), `testAndroidHostTest`, or `desktopTest`; run the `run-module-tests` skill to pick.
./gradlew :aktual-account:vm:testAll

# Formatting
./scripts/ktfmt.sh            # format files changed since main
./scripts/ktfmt.sh check      # check-only
./scripts/ktfmt.sh --force    # all files

# Run a Gradle task on only the modules with changes since main (append --dry-run to preview).
# A change to the root build file, .github/, build-logic/, or libs.versions.toml runs all modules.
./scripts/detekt.sh           # detektCheck on changed modules
./scripts/lint.sh             # lint on changed modules
./scripts/test.sh             # testAll on changed modules

# Dependency graph — rerun only when module deps change
./gradlew atlasGenerate

# Force-refresh git version info (bypasses config cache)
./gradlew --rerun-tasks