scopes

Scopes is a local-first, AI-assisted task and project management tool that treats Projects, Epics, and Tasks as a unified entity called a Scope. It provides a recursive hierarchy, human-friendly aliases, and AI collaboration through comments to keep context with you as you work. Typical workflows involve creating scopes, assigning or aliasing them for quick lookup, and navigating a tree to inspect or modify nested scopes. You can search by alias, view a scope’s children, and create child scopes under a parent to build a nested workspace that always keeps context in sync with your directory focus. The MCP integration enables AI tools to participate in scope discussions by leaving comments, enabling seamless collaboration between developers and AI assistants while keeping data local and offline-capable when needed.

Available commands include creating scopes with automatic or custom aliases, linking multiple aliases to a single scope, listing or showing scopes by alias, and rendering hierarchical views. For example, you can create a scope with an auto-generated alias, add additional aliases for quick lookup, and then drill into a parent to create child scopes. The tool supports features like tab-completion when locating scopes by alias and a visual tree view to understand relationships at a glance. These capabilities are designed to work both offline and across devices, with local data staying private by design.

Beyond basic CRUD, Scopes provides workflows for workspace management, alias strategies, and AI-assisted collaboration through comments. This enables you to keep human and AI reasoning aligned within the same scope space, reducing context switching and supporting recursive project structures across your development lifecycle.

Prerequisites:

• Java Development Kit (JDK 17 or newer)
• Git
• Optional: Docker if you plan to run via containerized image

1. Clone the repository:

git clone https://github.com/kamiazya/scopes.git
cd scopes

2. Build the project (Gradle):

./gradlew build

This will compile the modules and produce runnable artifacts under build/ or similar output, depending on the project configuration.

3. Run the server locally (example):

./gradlew run

If a packaged jar is produced, you can start it with:

java -jar build/libs/scopes-*.jar

4. Alternatively, run via Docker (if you prefer containerized execution):

docker build -t kamiazya-scopes:latest .
docker run -it --rm kamiazya-scopes:latest

Notes:

• Adjust the exact Gradle task names if the project uses a custom lifecycle (e.g., ./gradlew :application:bootRun).
• Ensure your environment has network access if dependencies must be downloaded during build.
• For development, you may want to run tests with ./gradlew konsistTest or equivalent tasks as described in the project guidelines.

Tips and common considerations:

• The Scopes system is designed for offline-first operation; ensure local data directories are writable and backed up if needed.
• Aliases are case-insensitive and support prefix matching, so use memorable patterns like bold-tiger-x7k or auth-system to speed up lookups.
• When using MCP with AI collaborators, keep AI comments within the same scope context to minimize drift and maintain traceability.
• If you encounter issues with alias resolution, verify that the alias cache is synchronized with the latest scope definitions; you can resync or rebuild the index if provided by the tooling.
• The architecture emphasizes clean boundaries between domain layers; if you plan to extend or customize, follow the documented domain-driven design guidelines and ADRs.