Known Limitations

Kodebase is currently in Alpha. This page documents known limitations and sets expectations for early testers. We're iterating rapidly based on feedback.

Alpha Disclaimer

Expect breaking changes between releases. During the Alpha phase:

• APIs and artifact schemas may change without migration paths
• Configuration formats may be updated
• New features may replace existing functionality

Recommendation: Always use npx kodebase@latest to stay current with the latest fixes and features. Kodebase will notify you when updates are available.

Platform Support

Platform	Status	Notes
macOS	Tested	Primary development platform
Linux	Partially tested	Should work, please report issues
Windows	Untested	May have path handling issues

If you encounter platform-specific issues, please report them on GitHub with your OS version.

VSCode Extension

The Kodebase VSCode extension is available as a pre-release .vsix file:

• Not yet published to the VSCode Marketplace
• Requires manual installation via "Install from VSIX..."
• May require reinstallation after updates

See the Installation Guide for detailed instructions.

MCP Server Behavior

Restart Required After Config Changes

After updating your MCP configuration file, you must restart your AI assistant (Claude Code or Cursor) for changes to take effect. The MCP server reads configuration at startup.

Session State

Scout sessions are stored in memory. If the MCP server restarts:

• Active Scout sessions will be lost
• You'll need to start a new session with scout_start_session
• Completed artifacts in .kodebase/artifacts/ are persisted and unaffected

Error Messages

Some error messages are not yet user-friendly. If you encounter an unclear error:

1. Check the Troubleshooting Guide for common issues
2. Try running the MCP server manually to see detailed output:

   KODEBASE_PROJECT_ROOT=/path/to/project npx kodebase@latest

3. Report the error on Discord or GitHub Issues

Documentation

Documentation may occasionally lag behind code changes during the Alpha phase. If you notice discrepancies:

• Check the GitHub Releases for the latest changes
• The MCP tools have inline descriptions that are always current
• Ask your AI assistant: "What parameters does scout_start_session accept?"

Known Issues

Current known issues (as of Alpha launch):

1. Large artifact hierarchies may cause slow initial load times
2. Complex dependency chains are not yet fully validated during artifact generation
3. Git hooks require manual setup with kb init (auto-detection planned)

Check GitHub Issues for the current list of known bugs.

Staying Updated

Version Notifications

Kodebase displays version information on MCP server startup and alerts you when updates are available:

Kodebase v0.3.1

┌──────────────────────────────────────────────┐
│  Update available: 0.3.1 → 0.4.0             │
│  Run: npx kodebase@latest                    │
└──────────────────────────────────────────────┘

Tracking Changes

• Releases: github.com/kodebaseai/kodebase/releases
• Changelog: Included in each release with breaking changes highlighted
• Discord: Announcements channel for major updates

Reporting Issues

We welcome feedback from Alpha testers!

Discord (Preferred for Discussion)

Join discord.gg/dSWFC5Da to:

• Get help from the community
• Discuss feature requests
• Share your experience

GitHub Issues (Preferred for Bugs)

Report bugs at github.com/kodebaseai/kodebase/issues with:

• Your operating system and version
• Node.js version (node --version)
• Kodebase version (shown at MCP server startup)
• Steps to reproduce the issue
• Full error message or screenshot

What's Next

We're actively working on:

• Improved error messages and validation
• Windows platform support
• VSCode Marketplace publishing
• Performance optimizations for large projects

Your feedback directly shapes our priorities. Thank you for being an Alpha tester!