AGENTS.md - LLM Agent Development Guide
Project: Kilo Companion Android App
Purpose: This document serves as the central coordination hub for LLM agents working on this project. It contains architectural decisions, development workflows, and agent-specific instructions.
Project Overview
This is a native Android "Companion Wrapper" application for OpenCode and Kilo CLI tools. The app acts as a:
- Configuration Dashboard
- Authentication Handler
- Web Wrapper for local CLI interfaces
Key Design Decisions
- No Native Node Execution: The app does NOT embed Node.js. It manages configuration files and provides UI wrappers.
- Shared Storage Pattern: Uses
Documents/KiloWorkspaceas a shared directory accessible by both the Android app and Termux/CLI. - Jetpack Compose UI: Modern declarative UI framework for Android.
- OAuth Intent Handling: Custom URI scheme interception for seamless auth flows.
Directory Structure
/workspace/
├── AGENT_SCRATCH/ # LLM agent workspace and documentation
│ ├── AGENTS.md # This file - master agent guide
│ ├── DECISIONS.md # Architecture decision records
│ ├── PROGRESS.md # Development progress log
│ └── WORKFLOW.md # Development workflow documentation
├── kilo-companion-app/ # Main Android project
│ ├── app/ # Android app module
│ ├── scripts/ # Build and utility scripts
│ └── gradle/ # Gradle wrapper
├── docs/ # Project documentation
│ └── PROJECT-INIT-PROMPT.md # Original requirements
├── build-android.sh # Linux x86-64 build script
├── termux-build.sh # Android arm64 build script
├── install-prerequisites.sh # Dependency installer
└── auto-git.sh # Automated git commit script
Development Workflow
1. Automated Git Tracking
Run the auto-git script in a separate terminal:
./auto-git.sh
This commits changes every 60 seconds with timestamps.
2. File Naming Conventions
- Kotlin files:
PascalCase.kt - XML resources:
snake_case.xml - Scripts:
kebab-case.sh - Documentation:
UPPERCASE.mdfor important docs,PascalCase.mdfor guides
3. Code Organization
// Package structure
com.kilo.companion
├── data/ # Data models and file I/O
├── ui/
│ ├── screens/ # Full-screen Composables
│ ├── components/# Reusable UI components
│ └── theme/ # Colors, typography, shapes
└── utils/ # Utility functions
4. Comment Standards
All code must include:
- File-level documentation explaining purpose
- Function-level KDoc comments
- Inline comments for complex logic
- Permission handling explanations
Example:
/**
* SharedStorageManager.kt
*
* Manages file operations in the shared workspace directory.
* Handles permission requests and file I/O for configuration files.
*
* @author Kilo Companion Team
* @since 1.0.0
*/
Build Instructions
Linux x86-64 (Standard Build)
# Install prerequisites
./install-prerequisites.sh
# Build debug APK
./build-android.sh debug
# Build release APK
./build-android.sh release
Termux on Android (arm64)
# In Termux
./termux-build.sh
See TERMUX.md for detailed mobile development instructions.
Testing Checklist
Before marking a task complete:
- Code compiles without warnings
- All permissions properly declared
- Error handling implemented
- Comments added for complex logic
- Auto-git is running
- Documentation updated
Common Issues & Solutions
Issue: Gradle Daemon Locks
Solution: Run ./gradlew --stop before builds
Issue: Permission Denied on Scripts
Solution: Run chmod +x *.sh
Issue: Out of Memory during Build
Solution: Add org.gradle.jvmargs=-Xmx2048m to gradle.properties
Agent Communication Protocol
When updating this file or creating new agent documentation:
- Use markdown format exclusively
- Keep sections clearly separated
- Update TODO lists when completing work
- Log significant decisions in DECISIONS.md
- Record progress in PROGRESS.md
External Resources
Last Updated: 2026-03-02
Version: 1.0.0
Status: Active Development