Prerequisites
Before setting up ClawControl for local development, ensure you have the following installed:
- Bun - Required runtime for the CLI (used by @opentui/core)
- Node.js >= 20.0.0 - JavaScript runtime
- pnpm 10.25.x - Package manager
Install Bun
If you don’t have Bun installed:curl -fsSL https://bun.sh/install | bash
Clone the repository
git clone https://github.com/ipenywis/clawcontrol.git
cd clawcontrol
Run the development server
This runs ClawControl locally with hot-reload enabled using Bun’s --watch flag. Available Scripts
The following npm scripts are available in package.json:
Development
Runs the CLI in development mode with automatic reloading on file changes. Uses bun --watch src/index.tsx.
Build
Builds the production bundle using tsup. The output is generated in the dist/ directory as ESM modules targeting ES2022.
Build configuration is in tsup.config.ts:
- Entry point:
src/index.tsx
- Format: ESM
- Target: ES2022
- External dependencies:
@opentui/core, @opentui/react, react, ssh2, cpu-features
@opentui/core must remain external because it uses Bun-specific features like bun:ffi and Bun import attributes that cannot be bundled.
Start
Runs the built version from dist/index.js using Bun.
Type Checking
Runs TypeScript type checking without emitting files. Uses tsc --noEmit to validate types across the codebase.
Testing
Runs all tests using Vitest in run mode (non-watch). See Testing for more details.
Pre-publish
Automatically runs before publishing to npm. Executes pnpm build to ensure the latest version is bundled.
Local Development Workflow
Running Locally
-
Start development mode:
-
Make changes to source files in
src/
-
Test your changes - The CLI will automatically reload
-
Run type checks to catch errors:
-
Run tests to ensure everything works:
Testing the Built Version
To test the production build:
Or test the binary wrapper:
pnpm build
node bin/clawcontrol.js
Development with Provider APIs
When testing deployments locally, you’ll need valid API keys for cloud providers:
These keys are stored securely in ~/.clawcontrol/secrets.json when you create a deployment.
Project Configuration
TypeScript Configuration
The project uses TypeScript with the following key settings (tsconfig.json):
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "bundler",
"jsx": "react-jsx",
"jsxImportSource": "@opentui/react",
"strict": true,
"baseUrl": ".",
"paths": {
"@/*": ["src/*"]
}
}
}
- JSX: React JSX with
@opentui/react as the import source
- Module Resolution: “bundler” mode for modern bundler compatibility
- Strict Mode: Enabled for type safety
- Path Aliases:
@/* maps to src/*
Package Manager
The project is locked to [email protected] via the packageManager field in package.json. This ensures consistent dependency resolution across development environments.
Troubleshooting
Bun Not Found
If you get “bun: command not found”:
curl -fsSL https://bun.sh/install | bash
# Then restart your shell or run:
source ~/.bashrc # or ~/.zshrc
Module Resolution Errors
If you encounter module resolution errors:
-
Clear node_modules and reinstall:
rm -rf node_modules
pnpm install
-
Ensure you’re using the correct Node version:
node --version # Should be >= 20.0.0
Type Errors
Run type checking to see detailed errors:
Common issues:
- Missing
@types/* packages (should be in devDependencies)
- JSX configuration mismatch (check
tsconfig.json)
Next Steps