DriveClaw

DriveClaw is a production-minded MVP for a Telegram-only dev bot that accepts .zip project uploads, archives originals in Google Drive, analyzes projects without executing uploaded code, pushes code to GitHub, and deploys to Vercel.

Why it exists

DriveClaw is designed for tiny infrastructure:

• 1 CPU core
• 512 MB RAM
• no browser dashboard
• no database-backed control plane
• low-complexity first version

It favors bounded actions, explicit user approval, short-lived workspaces, and modular integrations over heavyweight orchestration.

Architecture

• main.py: CLI entrypoint and bot bootstrap
• core/: config loading and logging
• bot/: Telegram command handlers and onboarding conversations
• services/: bootstrap, memory, workspace safety, project detection, and per-user settings storage
• integrations/: Telegram download helpers plus Google Drive, AI, GitHub, and Vercel clients
• jobs/: upload-analysis and deploy orchestration
• memory/: single-file operational memory
• prompts/: compact AI prompt templates
• data/: file-backed runtime state for jobs and per-user settings

Low-resource design goals

• polling instead of a web stack
• file-based job and user state
• safe zip extraction with size limits
• no uploaded code execution
• heuristic project detection first, AI summary second
• isolated per-user credentials stored separately from admin config
• always clean extracted workspaces after each job

Setup

1. Install Python 3.11+.
2. Install the package:

pip install -e .

3. Run terminal bootstrap:

driveclaw bootstrap

You can also run:

python main.py --bootstrap

4. Start the bot:

driveclaw run

Or:

python main.py

Bootstrap walkthrough

The owner bootstrap asks for:

• bot/app name
• Telegram bot token
• default AI provider and models
• enabled Google integrations
• Google credentials paths
• admin GitHub and Vercel tokens
• storage roots
• memory file path
• auto-deploy and cleanup defaults

It writes:

• config.toml for non-secret owner settings
• .env for admin secrets
• memory/project_memory.txt if it does not exist

Two-level onboarding

1. Admin bootstrap

Owner-only terminal onboarding sets shared runtime defaults and optional admin tokens.

2. User onboarding inside Telegram

Each Telegram user runs /connect and stores their own:

• AI provider
• AI API key
• default model
• fast model
• fallback model
• GitHub token
• Vercel token
• enabled Google tools
• Google credentials/config reference
• auto-deploy and auto-cleanup preferences

Per-user data is stored under:

• data/users/{telegram_user_id}/profile.json
• data/users/{telegram_user_id}/secrets.json

This keeps credentials isolated per user and makes the storage backend easy to swap later.

Commands

• /start
• /help
• /upload
• /status
• /deploy
• /restore
• /cleanup
• /memory
• /config
• /bootstrap
• /connect
• /settings
• /providers
• /tokens
• /google

Google integrations

Supported toggles in bootstrap and user settings:

• Drive
• Gmail
• Calendar
• Docs
• Sheets

Current v1 state

• Google Drive: implemented as the archive/report storage target
• Gmail, Calendar, Docs, Sheets: modular stubs with clean interfaces for later wiring

Google Drive folder layout:

DriveClaw/
  users/
    {username_or_userid}/
      {project_slug}/
        original/
        processed/
        reports/

AI provider configuration

The scaffold separates:

• provider name
• default model
• fast model
• fallback model
• API key

Current provider implementation status:

• OpenAI: basic support
• OpenRouter: basic support
• Anthropic: basic support
• Google: stubbed for later wiring
• Stub mode: local fallback summary with no external AI call

GitHub setup

DriveClaw uses the GitHub API to create repositories and local git commands to push extracted source trees. It never runs uploaded project code.

Vercel setup

DriveClaw uses the Vercel deployment API after a GitHub push. The deployment polling loop stays intentionally small and bounded.

Telegram bot setup

Create a bot with BotFather, copy the token into bootstrap, then start the polling worker. Users onboard themselves inside Telegram with /connect.

Memory file

DriveClaw keeps a single operational memory file at memory/project_memory.txt with:

• CURRENT SUMMARY
• RECENT DECISIONS
• PROJECT RECORDS
• ACTION LOG

The summary is compact and refreshed in place. The lower sections are append-only and lightly pruned to avoid bloating.

Cleanup behavior

DriveClaw always deletes extracted temp workspaces after analysis and after deploy. The user auto_cleanup preference currently controls whether cached local archives are removed once the archive has already been persisted to Drive.

Security notes

• Uploaded code is never executed directly.
• Zip extraction rejects unsafe paths and oversized archives.
• Per-user secrets live in separate directories and files.
• Admin tokens are not copied into user records.
• Admin fallback token usage is disabled by default.

Limitations

• No web dashboard
• No database state store
• No arbitrary code execution
• No multi-agent orchestration
• Gmail, Calendar, Docs, and Sheets are still stubs
• Google OAuth refresh/token lifecycle still needs more production hardening
• Vercel Git deployment assumptions may need project-specific tuning

Troubleshooting

• If the bot does not start, rerun bootstrap and verify TELEGRAM_BOT_TOKEN in .env.
• If Drive uploads fail, verify Google credentials path and enabled Drive integration.
• If GitHub push fails, confirm git is installed and the token has repo permissions.
• If Vercel deploy fails, inspect the latest job status and report, then use /settings and /tokens to update credentials.

Roadmap

• encrypted secret storage backend
• richer Google OAuth flow per user
• report artifact uploads for deploy failures
• better framework heuristics and monorepo support
• optional queueing and retry backoff