Self-Improvement

Talome is the first self-hosted platform that improves its own source code. When you report a slow page, a UI bug, or ask for a new feature, the AI reads the relevant source files, understands the implementation, writes a targeted modification, runs the TypeScript compiler, and either commits the change or rolls it back. Every step is audited.

This isn't theoretical. The AI has access to the full Talome monorepo, understands the architecture, and has purpose-built tools for safe code modification. You can watch it plan a change, review the diff, approve it, and see the result on your next page refresh.

The Three-Stage Pipeline

Self-improvement follows a strict plan-apply-verify pipeline. No stage can be skipped.

Stage 1: Plan

The plan_change tool reads the relevant source files, understands the current implementation, and generates a detailed change plan. This is a read-only operation — nothing is modified.

The plan stage is critical because it lets you review what will change before anything is modified. The AI shows:

• Which files will be touched
• What the current code does
• What the new code will do
• Why the change improves things

Stage 2: Apply

The apply_change tool writes the modification and immediately validates it:

What happens inside apply_change:

1. The modification is written to disk
2. pnpm exec tsc --noEmit runs from the affected app directory
3. If compilation succeeds — the change is committed to git with a descriptive message
4. If compilation fails — the change is automatically stashed with git stash, the error is reported, and the codebase returns to its previous state

The apply stage runs in a detached worker process that survives server restarts. If Talome restarts mid-apply, the worker finishes and reports the result when the server comes back.

Stage 3: Verify

After applying, you can:

• Test the change — refresh the page or trigger the behavior that was fixed
• Review the diff — list_changes shows the full history with before/after
• Roll back — rollback_change reverts the most recent change cleanly

Safety Mechanisms

Every safety net exists because self-modifying code is inherently dangerous. Here's what prevents the AI from breaking your system:

What Happens on Failure

The failed change is never lost — it's in the git stash. But your running codebase is never broken.

Supervisor Protection

After a self-improvement change is applied and the backend restarts, the supervisor monitors whether the new code is stable:

1. 60-second grace period — immediately after a code change restart, crashes are tolerated without escalation. Transient startup issues resolve themselves.
2. Clean-tree awareness — if the working tree is clean (changes were committed), the supervisor falls through to AI diagnosis instead of uselessly stashing.
3. Dashboard autofix — if the dashboard crashes with build errors, Claude Code attempts a fix automatically before reverting.
4. Known-good safety — reverts never overwrite code that's ahead of the known-good tag, protecting committed improvements.

Recovering from a Revert

If the supervisor reverted your changes, they're in the git stash:

git stash list                    # see what was stashed
git stash show -p stash@{0}      # inspect the most recent stash
git stash pop stash@{0}          # restore it

What the AI Can Improve

Performance Optimizations

• Database query efficiency (N+1 queries, missing indexes)
• React render optimization (memoization, virtual scrolling)
• API response caching
• Docker API call batching
• Bundle size reduction

Bug Fixes

• Error handling for edge cases
• Race conditions in async code
• Type mismatches caught at runtime but not compile time
• UI state inconsistencies

UI Enhancements

• Layout improvements
• Responsive design fixes
• Accessibility improvements
• New component variants
• Theme adjustments

New Features

• New API routes and tools
• New dashboard pages and widgets
• New integration tools for additional apps
• Automation enhancements
• Custom tool templates

Complete Transcript: Performance Fix

Here's an end-to-end example of the AI identifying and fixing a real performance issue:

Custom Tool Creation

For runtime extensions that don't require modifying Talome's source code, use create_tool instead of apply_change.

When to Use create_tool vs. apply_change

How Custom Tools Work

Custom tools are written to ~/.talome/custom-tools/, loaded at runtime via jiti (a TypeScript-aware module loader), and automatically registered in the tool registry. They persist across restarts.

Dangerous patterns (eval, exec, filesystem writes outside allowed paths) are blocked during tool creation.

Issue Tracking

The AI has a built-in issue tracker for improvements and bugs:

Issues appear on the Evolution page in the dashboard, where you can see all tracked bugs, feature requests, and their status.

Issue Types

Scheduling Improvements

Combine self-improvement with automations for overnight maintenance:

Key Codebase Paths

When the AI plans a change, it reads from these locations:

Limitations

• No files outside the project root — the AI cannot modify system files, home directory configs, or other repositories
• No global package installs — npm install -g, brew install, or similar commands are blocked
• No system-level changes — no modifying /etc/, no changing shell configs, no touching Docker daemon settings
• TypeScript must pass — every single change is validated. There are no exceptions, no flags to skip it, no force-commit options
• One change at a time — the AI must confirm each change's success before attempting the next. No batch modifications.
• Destructive tier — apply_change and rollback_change require confirmation in the default security mode