Contributing to Maka

• Where to start
• Quick start
• Developing Maka
• Branch naming
• Pull requests
• License

Where to start

These changes merge most readily:

• Bug fixes
• Model provider support — a new provider, or a fix to an existing one
• Tests and stability work
• Performance improvements
• Documentation
• Fixes for environment-specific problems

Product and UI changes are different: open an issue and agree the direction before implementing. Maintainers land features directly because they set that direction; an outside contributor is better off confirming it first.

Looking for something to pick up:

• help wanted
• good first issue
• bug
• enhancement

To claim one, say so in a comment and a maintainer may assign it to you.

Prefer the Bug report or Feature request template when opening an issue — they ask for the context that makes one actionable. Report security problems through the private flow in SECURITY.md, never as a public issue.

Quick start

Requirement	Value
Node	>=22.19.0 (engines, root package.json)
npm	11.12.1 (packageManager)
Platform	macOS Apple Silicon for desktop work. Releases also ship an unsigned Windows x64 build and CI runs a non-blocking windows_baseline job, but Windows and Linux are not supported targets yet

git clone https://github.com/maka-agent/maka-agent.git
cd maka-agent
npm install                 # root only — never inside a workspace
npm run build               # builds every workspace in dependency order
npm --workspace @maka/core test

Architecture is documented in ARCHITECTURE.md.

Developing Maka

Running

npm run dev          # desktop app with HMR
npm run dev:full     # full build, then launch the desktop app

npm --workspace maka-agent exec -- maka          # TUI
npm --workspace maka-agent exec -- maka run "…"  # one non-interactive turn

Headless commands live in packages/headless/README.md.

Building

npm run build builds workspaces in dependency order:

code-mode → core → storage → mcp → runtime → runtime-host
          → computer-use → headless → maka-agent → ui → desktop

Building one workspace only succeeds when its dependencies are already built — @maka/runtime compiled against a stale @maka/core produces type errors that look like problems in the code you just wrote. When unsure, build from the root.

The desktop app has four outputs; build:test covers the first three:

npm --workspace @maka/desktop run build:main      # main process
npm --workspace @maka/desktop run build:preload   # preload bridge
npm --workspace @maka/desktop run build:overlay   # overlay windows
npm --workspace @maka/desktop run build:renderer  # renderer

Testing

Tests run against compiled output in dist/. Every workspace's test script cleans, builds, then runs node --test. Always go through it — calling node --test after a bare build:* executes orphaned artifacts from older trees, which fail on imports that no longer resolve.

npm test                                 # all workspaces
npm --workspace @maka/core test          # one workspace
npm run test:scripts                     # repository scripts
npm --workspace @maka/desktop run e2e    # Playwright

Before pushing

CI runs these; matching them locally avoids a slow round trip.

npm run lint            # biome lint
npm run format:check    # biome format — separate from lint; passing one proves nothing about the other
npm run build
npm run typecheck       # 4 tsconfig projects for desktop, including renderer and storybook
npx knip --workspace apps/desktop
npx knip --workspace packages/ui

The CI job named typecheck runs all of them under bash -e, so the first failure aborts the rest — read which step failed, not the job name.

Branch naming

<type>/<description>

<description> is lowercase and hyphen-separated. <type> must be one of:

Prefix	Meaning
feat	New feature
fix	Bug fix
refactor	Behavior-preserving restructuring
test	Test-only change
chore	Build, dependency, and housekeeping work
perf	Performance improvement
docs	Documentation-only change
ci	CI configuration and pipelines
build	Build system and artifacts

Pull requests

Opening a pull request pre-fills pull_request_template.md, which carries the required sections and the checklist. Fill it in rather than replacing it.

Title. The repository squash-merges, so the title becomes the commit on main. Follow Conventional Commits:

<type>(<scope>): <summary>

<type> is the set in branch naming. <scope> is the workspace or area — desktop, ui, runtime, headless, settings, runtime-host, storage, core, cli, deps, computer-use, scripts, release, windows, e2e, security, and so on — git log shows the set in use.

fix(desktop): classify provider action errors from the unwrapped IPC message
feat(runtime): decouple Swarm with asynchronous wakeups
test(core): pin the shared validation corpus to every envelope value domain

UI changes. Include before/after screenshots or a recording. A visual change cannot be judged from a diff.

Keep the description short and your own. Long generated write-ups slow review down. Say what changed and why in your own words; if that needs many paragraphs, the pull request is probably too large.

License

By contributing you agree that your contributions are licensed under the Apache License 2.0.