Claude Kontrol

Telefondan PC'yi Claude AI ile uzaktan kontrol eden kişisel asistan. Web tabanlı arayüz + opsiyonel Android (Capacitor) APK kabuğu.

Ne yapar?

Sohbet kutusundan komut yaz / söyle, Claude PC'de iş yapar (uygulama açar, dosya yazar, mesaj atar, vs.)
Telefonu trackpad/klavye olarak kullan, PC ekranını canlı izle (60 fps'e kadar)
Dosya alışverişi (telefon→PC ataç, PC→telefon indirme kartı)
Hands-free dinleme, sesli yanıt (TTS), bildirimler

Kişisel kullanım için tasarlanmış, tek kullanıcı, tek PC.

Mimari

   +------------+        +-------------------+        +-------------------+
   |  Telefon   | -----> |  Tailscale tunnel | -----> |  PC (FastAPI)     |
   |  (PWA/APK) |  HTTPS |  (mesh, ücretsiz) |        |  app.py + uvicorn |
   +------------+        +-------------------+        +---------+---------+
                                                                |
                                +-------------------------------+--------+
                                |                |              |        |
                          Claude Agent SDK   pyautogui      mss + PIL   ...
                          (subscription)     (mouse/kbd)    (ekran)
                                |
                                v
                          Claude Code (login)
                          + custom MCP tools
                          (open_app, click,
                           find_text, share_file,
                           take_screenshot, ...)

Kullanıcı ile sunucu arasında stabil bir HTTPS tüneli için Tailscale Funnel kullanılır (telefonda Tailscale kurulu olduğunda direkt mesh, üzerinden mobil veriden bile düşük gecikme).

Özellikler

Alan	Detay
Sohbet	Streaming yanıt · sohbet geçmişi · pin · arama · edit/regenerate · uzun dokunarak menü · model seçici (Haiku/Sonnet/Opus)
Uzaktan Kontrol	Canlı ekran (3-60 fps) · trackpad (ivmeli, yatay/dikey scroll) · klavye + özel tuşlar/kısayollar/F1-F12 · ekrana dokun-tıkla (interaktif) · PiP floating mini ekran
Sesli	Mikrofon (native plugin) · TTS · hands-free (uyandırma kelimesi: "Claude")
Dosya	Telefondan yükleme (kamera/galeri/dosya seçim menüsü) · PC'den indirme kartı · Claude `share_file` tool ile gönderir
Macros / Rutinler	Tek dokunuşla çalışan kişisel komut zincirleri
GUI Otomasyon (Claude için)	`take_screenshot` (cursor görünür) · `click` · `type_text` (Türkçe destekli) · `press_key` · `hotkey` · `scroll` · `drag` · `open_app` (URI/AUMID/exe/Win+search/web fallback) · `find_text` (Windows native OCR) · `list_windows` · `focus_window` · `get_active_window` · `take_region_screenshot`
Diğer	Karanlık/aydınlık tema · 3 yazı boyutu · stats (model, son 5 saat, bugün, toplam) · tehlikeli komut için `bypassPermissions` modu (kişisel kullanım) · şifre + brute-force koruması

Kurulum

1. Bağımlılıklar (Windows + Python 3.10+)

git clone <repo>   # veya zip indir
cd claude-kontrol
python -m venv venv          # opsiyonel ama önerilir
venv\Scripts\activate
pip install -r requirements.txt

2. Claude Code CLI

Claude Agent SDK Claude Code'un üzerinden çalışır, abonelik tüketir (API key'e gerek yok).

npm install -g @anthropic-ai/claude-code
claude
# Açılan promptta /login yaz, tarayıcıdan claude.ai (Pro/Max) hesabınla giriş yap

3. Tailscale (uzaktan erişim için)

PC'ye Tailscale kur, giriş yap.
Funnel'i aç (PC'de stabil HTTPS URL almak için):
```
tailscale funnel --bg 5000
```
Sana https://<makinen>.tail<id>.ts.net URL'i verir.
Telefona da Tailscale yükle, aynı hesapla giriş yap → telefon bu URL'e direkt mesh üzerinden bağlanır (Funnel hop'u atlar, latency düşer).

4. Konfigürasyon (opsiyonel)

.env.example dosyasını .env olarak kopyala ve değerleri ayarla:

cp .env.example .env

Değişken	Varsayılan	Anlamı
`KONTROL_PASSWORD`	`change-me`	Web/PWA login şifresi — sunucuyu açmadan önce mutlaka değiştir
`KONTROL_PORT`	`5000`	FastAPI portu
`KONTROL_WORKING_DIR`	(boş = `~`)	Claude'un işlem yaptığı klasör
`KONTROL_MAX_LOGIN_ATTEMPTS`	`5`	Brute-force eşiği
`KONTROL_LOGIN_BLOCK_MINUTES`	`15`	Eşik aşılınca block süresi

.env yoksa veya python-dotenv kurulu değilse hardcoded varsayılanlar kullanılır.

5. Çalıştırma

start.bat

Şunu görmelisin:

============================================================
  Claude Kontrol  v1.0
  http://localhost:5000
============================================================

Telefondan Tailscale URL'ine git → şifreni gir → "Ana ekrana ekle" ile PWA olarak kur. Ya da Capacitor APK'sını kur (aşağıda).

6. Capacitor APK (opsiyonel — native Android wrapper)

Native bildirim, mikrofon, kamera, geri tuşu gibi özellikleri tam kullanmak için. Tamamı capacitor-app/BUILD.md'de.

Özetle:

Java JDK 17+ ve Android Studio kur
capacitor-app/capacitor.config.json ve capacitor-app/www/index.html içindeki your-machine.tailXXXX.ts.net placeholder'ını kendi Tailscale Funnel adresinle değiştir
cd capacitor-app && npm install
npx cap sync android
npx cap open android → Android Studio açılır → Build → Generate Signed Bundle / APK

İçerik (HTML/JS/CSS) Tailscale URL'inden yüklendiği için, web tarafında değişiklik yaptığında APK'yı yeniden derlemen gerekmez — telefonu kapat-aç yeterli.

Kullanım Örnekleri

Telefondan sohbet kutusuna yazabilirsin/söyleyebilirsin:

"WhatsApp aç ve Ali'ye 'akşam buluşalım' yaz"
"Notepad aç, içine 3 paragraf bir blog yazısı yaz, Masaüstü'ne kaydet"
"Spotify'da klasik müzik aç"
"Gmail'de en son 5 maili özetle"
"İndirilenler klasöründeki en son PDF'i bana gönder"
"Bilgisayarımı 10 dakika sonra kapat"
"Hangi pencereler açık?"

Geliştirme

Dosya yapısı

claude-kontrol/
├── app.py                  # FastAPI backend + MCP tools
├── chat.html               # Ana arayüz (vanilla JS)
├── login.html              # Login sayfası
├── start.bat               # Sunucuyu başlatır
├── requirements.txt        # Python deps
├── .env.example            # Config şablonu
├── .gitignore
├── README.md               # bu dosya
├── scripts/
│   ├── generate_icons.py   # PWA ikonları (static/'a yazar)
│   └── generate_android_assets.py  # Capacitor android ikonları
├── static/                 # Manifest, ikonlar, sw.js, assetlinks
├── capacitor-app/          # Android wrapper (BUILD.md içinde)
├── data.db                 # SQLite (gitignore)
└── uploads/                # Yüklenen dosyalar (gitignore)

MCP tool eklemek

app.py içindeki @tool(...) decorator'ı kullan, sonra kontrol_mcp = create_sdk_mcp_server(...) ve allowed_tools=[...] listelerine ekle. Tool fonksiyonları _tool_ok(text) / _tool_err(text) helper'larıyla tutarlı format döndürmeli.

İkonları yeniden üretmek

Logo değiştirdikten sonra:

python scripts/generate_icons.py
python scripts/generate_android_assets.py     # Capacitor android için

Troubleshoot

Sorun	Çözüm
`'whatsapp'` Windows tarafından bulunamıyor dialog'u	Bilinen sorun değil — `_KNOWN_APPS` mapping'i kayıtlı handler arar, yoksa Get-StartApps + AUMID dener, en son web fallback'e düşer
Port 5000 in use hatası	`Get-Process python \| Stop-Process -Force` sonra start.bat
Mikrofon Capacitor APK'da çalışmıyor	APK rebuild gerek (manifeste `RECORD_AUDIO` izni ekledik). Ayrıca uygulamada izin diyaloğunu onaylaman lazım
Screenshot tool `'data'` hatası	Eski kod çalışıyor demektir. `start.bat` penceresini kapat → Görev Yöneticisi'nden Python süreçlerini öldür → tekrar aç
Kaspersky python.exe'yi engelliyor	Klasörü Kaspersky exception'a ekle (Settings → Threats and Exclusions → Add)
mss "thread" hatası	`app.py` thread-local mss instance kullanıyor; restart yeterli
WhatsApp Desktop yerine web açılıyor	Desktop kuruluysa Get-StartApps onu bulmalı. Test: PowerShell'de `Get-StartApps \| where Name -like "WhatsApp"`
Logo telefonda eski görünüyor	APK'yı kaldır → yeniden kur. Telefon ana ekranı eski ikonu cache'ler
Capacitor build "non-ASCII path" uyarısı	`capacitor-app/android/gradle.properties`'ta `android.overridePathCheck=true` kayıtlı (yol `Masaüstü` içerdiği için)

Sınırlar

iOS yok — Capacitor desteklerse de bu projede setup edilmedi
FCM push yok — uygulama tamamen kapalıyken bildirim gönderilmiyor (foreground/background sınırlı). LocalNotifications uygulama açıkken çalışıyor
Tek kullanıcı — multi-user için tasarlanmadı
PC açık olmalı — sunucu PC'de çalıştığı için açık olmadığında erişim yok
Login/2FA bypass yok — Claude şifre veya CAPTCHA giremez, kullanıcıdan ister
DRM/oyunlar tam yakalanmaz — DXGI lock'lı tam ekran içerik mss tarafından okunamayabilir

Güvenlik

HTTPS sadece Tailscale tüneli üzerinden — tail*.ts.net domaininde gerçek sertifika
Şifre brute-force koruması: 5 yanlış denemede 15 dakika ban
Cookie HTTP-only
Claude SDK bypassPermissions modunda çalışır — Claude tüm tool'ları onay sormadan kullanır (kişisel kullanım için isteneni; başka birine açacaksan permissions ekle)
Keystore (APK imzalama) kesinlikle yedeklenmeli — kaybolursa APK'yı güncelleyemezsin

Lisans

Kişisel proje, herhangi bir lisans iddiası yok. İstediğin gibi kullan/değiştir.

Navigation Menu

Repository files navigation

Claude Kontrol

Mimari

Özellikler

Kurulum

1. Bağımlılıklar (Windows + Python 3.10+)

2. Claude Code CLI

3. Tailscale (uzaktan erişim için)

4. Konfigürasyon (opsiyonel)

5. Çalıştırma

6. Capacitor APK (opsiyonel — native Android wrapper)

Kullanım Örnekleri

Geliştirme

Dosya yapısı

MCP tool eklemek

İkonları yeniden üretmek

Troubleshoot

Sınırlar

Güvenlik

Lisans

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
capacitor-app		capacitor-app
core		core
scripts		scripts
static		static
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
app.py		app.py
chat.html		chat.html
login.html		login.html
requirements.txt		requirements.txt
start.bat		start.bat

Folders and files

Latest commit

History

Repository files navigation

Claude Kontrol

Mimari

Özellikler

Kurulum

1. Bağımlılıklar (Windows + Python 3.10+)

2. Claude Code CLI

3. Tailscale (uzaktan erişim için)

4. Konfigürasyon (opsiyonel)

5. Çalıştırma

6. Capacitor APK (opsiyonel — native Android wrapper)

Kullanım Örnekleri

Geliştirme

Dosya yapısı

MCP tool eklemek

İkonları yeniden üretmek

Troubleshoot

Sınırlar

Güvenlik

Lisans

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages