Comprehensive AI Agent Workflow

Yapay Zeka Ajanları için Kapsamlı İş Akışı

Agent Harbor provides a complete ecosystem for AI-assisted development with desktop, web, and terminal interfaces, secure sandbox environments, and multi-platform support.

Agent Harbor; masaüstü, web ve terminal arayüzleri, güvenli sanal alan (sandbox) ortamları ve çoklu platform desteğiyle yapay zeka destekli geliştirmeler için eksiksiz bir ekosistem sunar.

Agent Harbor is a workflow designed to make working with AI coding assistants (like Claude Code, Codex, GitHub Copilot, Jules, etc.) smoother and more effective for developers.

Agent Harbor, geliştiricilerin yapay zeka kodlama asistanlarıyla (Claude Code, Codex, GitHub Copilot, Jules vb.) daha verimli ve sorunsuz çalışmasını sağlayan bir iş akışıdır.

Key Principles:

Temel Prensipler:

  • Simple Task Assignment: Developers describe coding tasks using a simple command-line tool (agent-task), creating a dedicated branch.
  • Secure Operation: The AI agent works in a secure, isolated environment (sandbox) without needing constant permission for its actions.
  • Complete Solutions: The agent finishes its work only when all tests pass, delivering a ready-to-merge code patch or pull request (PR).
  • Historical Record: Every task and its solution become part of the project's Git history, creating a clear audit trail and knowledge base.
  • Basit Görev Atama: Geliştiriciler, agent-task adlı basit bir komut satırı aracıyla görevleri tanımlar ve bu görevler için özel bir branch oluşturur.
  • Güvenli Çalışma: Yapay zeka asistanı, eylemleri için sürekli izin istemeye gerek duymadan, güvenli ve izole bir sanal alanda (sandbox) çalışır.
  • Eksiksiz Çözümler: Asistan, yalnızca tüm testler başarıyla geçtiğinde çalışmasını tamamlar ve birleştirmeye hazır bir kod yaması (patch) veya çekme isteği (pull request) sunar.
  • Geçmiş Kaydı: Her görev ve çözümü, projenin Git geçmişinin bir parçası haline gelerek denetlenebilir bir kayıt ve bilgi birikimi oluşturur.

This approach uses Git pushes to start cloud agents and automates other interactions. It supports local agents in development containers (devcontainers) and can use ZFS/Btrfs snapshots for faster startup. The workflow helps manage tasks in large codebases (monorepos) and works across different AI tools and environments.

Bu yaklaşım, bulut tabanlı ajanları başlatmak için Git push komutlarını kullanır ve diğer etkileşimleri otomatikleştirir. Geliştirme konteynerlerinde (devcontainer) yerel ajanları destekler ve daha hızlı başlatma süreleri için ZFS/Btrfs anlık görüntülerinden (snapshot) faydalanabilir. Bu iş akışı, büyük kod tabanlarındaki (monorepo) görevlerin yönetilmesine ve farklı yapay zeka araçları ile ortamlarında çalışmaya olanak tanır.

The main tools are agent-task (for developers to start tasks) and get-task (for agents to fetch instructions). It supports various agents like Codex, Jules, Goose, Open Hands, and GitHub Copilot through specific setup scripts.

Ana araçlar, geliştiricilerin görev başlatması için agent-task ve ajanların talimatları alması için get-task'tir. Codex, Jules, Goose, Open Hands ve GitHub Copilot gibi çeşitli ajanları özel kurulum betikleri aracılığıyla destekler.

How It WorksNasıl Çalışır?

Agent Harbor creates a structured workflow between developers and AI coding assistants, making collaboration smooth and efficient.

Agent Harbor, geliştiriciler ve yapay zeka kodlama asistanları arasında yapılandırılmış bir iş akışı oluşturarak iş birliğini sorunsuz ve verimli hale getirir.

1

Create Task

Görev Oluştur

Developer describes what needs to be built

Geliştirici, yapılacak işi tanımlar

2

AI Works

Yapay Zeka Çalışır

AI assistant implements the task

Yapay zeka asistanı görevi yerine getirir

3

Review & Merge

İncele ve Birleştir

Developer reviews completed work

Geliştirici, tamamlanan işi inceler

For DevelopersGeliştiriciler İçin

Start a new task with a simple command:

Basit bir komutla yeni bir görev başlatın:

# Create a new feature branch with task description
agent-task user-authentication-feature

# This command opens the editor for you to describe the task
# Example task description:
Implement user authentication with JWT tokens.
Include login, logout and password reset functions.
Write tests for all endpoints.

Command OptionsKomut Seçenekleri

The agent-task command accepts several options for non-interactive use:

agent-task komutu, etkileşim gerektirmeyen kullanım için çeşitli seçenekler sunar:

# Automatically push to remote server without asking
agent-task --push-to-remote=true feature-name

# Use text as task description instead of editor
agent-task --prompt="Implement user login feature" feature-name

# Read task description from file
agent-task --prompt-file=task-description.txt feature-name

# Save Nix dev shell to commit message
agent-task --devshell=csharp feature-name
# or use short form:
agent-task -s csharp feature-name

Setup CommandKurulum Komutu

Check available versions of codex and goose:

codex ve goose'un mevcut sürümlerini kontrol edin:

# Check available versions
agent-task setup

For AI AssistantsYZ Asistanları İçin

The AI assistant retrieves and works on the task:

Yapay zeka asistanı görevi alır ve üzerinde çalışmaya başlar:

# AI runs this command to understand the task
get-task

# Output shows the complete task description
# AI works on the implementation...
# When tests pass, AI creates a complete patch

get-task Optionsget-task Seçenekleri

The get-task command supports additional options:

get-task komutu ek seçenekleri destekler:

# Print only environment variable assignments
get-task --get-setup-env

Workflow Commandsİş Akışı Komutları

Task descriptions may include lines beginning with / (e.g. /front-end-task).

Görev tanımları / ile başlayan satırlar içerebilir (ör. /front-end-task).

When get-task is executed, these lines are replaced with the output of matching programs or text files in the .agents/workflows folder of your repository.

get-task çalıştırıldığında, bu satırlar deponuzun .agents/workflows klasöründeki eşleşen programların veya metin dosyalarının çıktısıyla değiştirilir.

# Example task with workflow command
Implement user authentication with JWT tokens.
Include login, logout and password reset functions.
Write tests for all endpoints.

# This line will be replaced with workflow output
/front-end-task

# get-task will search for these files:
# - .agents/workflows/front-end-task (executable file)
# - .agents/workflows/front-end-task.txt (text file)

@agents-setup Directives@agents-setup Direktifleri

Lines starting with @agents-setup in either the task file or the workflow output are stripped from the final message and interpreted as environment variable assignments for the *-setup scripts.

Görev dosyasında veya iş akışı çıktısında @agents-setup ile başlayan satırlar son mesajdan çıkarılır ve *-setup betikleri için ortam değişkeni atamaları olarak yorumlanır.

# Direct assignment
@agent-setup DEV_SHELL=csharp

# Add to comma-separated set
@agent-setup TESTED_COMPONENTS+=backend,db

# Multiple directives are combined
@agent-setup DEV_SHELL=csharp
@agent-setup TESTED_COMPONENTS+=frontend
@agent-setup TESTED_COMPONENTS+=api

Directive RulesDirektif Kuralları

  • Conflicting direct assignments (different values for the same variable) result in an error.
  • Çakışan doğrudan atamalar (aynı değişken için farklı değerler) hatayla sonuçlanır.
  • A direct assignment can be combined with one or more appends.
  • Doğrudan bir atama, bir veya daha fazla ekleme ile birleştirilebilir.
  • One or more append operations without a direct assignment simply combine their entries.
  • Doğrudan atama olmadan yapılan bir veya daha fazla ekleme işlemi, girişlerini basitçe birleştirir.
  • Duplicate directives or values are ignored.
  • Tekrarlanan direktifler veya değerler göz ardı edilir.

Get StartedBaşlarken

Install as Ruby GemRuby Gem Olarak Yükleyin

The scripts can be installed as a gem for easier reuse:

Betikler, daha kolay yeniden kullanım için bir gem olarak yüklenebilir:

# Install Agent Harbor as a gem
gem install --local agent-harbor.gem

This will provide the agent-task, get-task, and download-internet-resources executables in your PATH.

Bu, PATH dizininize agent-task, get-task ve download-internet-resources çalıştırılabilir dosyalarını ekleyecektir.

Bash CompletionBash Tamamlama

To enable bash completion for agent-task, source the script in your shell profile:

agent-task için bash tamamlamayı etkinleştirmek isterseniz, betiği shell profilinizde kaynak olarak ekleyin:

# Add to ~/.bashrc or ~/.zshrc file
source scripts/agent-task-completion.bash

Install with NixNix ile Yükleyin

This repository provides a Nix flake. The default package installs the agent-task binary with codex and goose available in its PATH.

Bu depo, bir Nix flake'i sağlar. Varsayılan paket, PATH'inde codex ve goose bulunan agent-task ikili dosyasını yükler.

# Run Agent Harbor
nix run github:blocksense-network/agent-harbor

Or install the utilities package:

Veya yardımcı programlar paketini kurun:

# Install agent-utils package
nix profile install github:blocksense-network/agent-harbor#agent-utils

The agent-utils package bundles the get-task and start-work binaries.

agent-utils paketi, get-task ve start-work ikili dosyalarını içerir.

Desktop ApplicationMasaüstü Uygulaması

# Run Electron desktop app
nix run github:blocksense-network/agent-harbor#electron-app

Terminal InterfaceTerminal Arayüzü

ah agent start # Starts TUI control panel

What's Included?Neler Dahil?

The core components include:

Temel bileşenler şunları içerir:

  • codex-setup: A script to initialize the workspace, download necessary internet resources, and run project-specific setup.
  • codex-setup: Çalışma alanını başlatan, gerekli internet kaynaklarını indiren ve projeye özgü kurulumu çalıştıran bir betik.
  • agent-task: A script for developers to begin a new task, automatically creating a dedicated branch and storing the task description.
  • agent-task: Geliştiricilerin yeni bir göreve başlamasını sağlayan, otomatik olarak özel bir branch oluşturan ve görev tanımını saklayan bir betik.
  • agent-task setup: Prints the versions of codex and goose available in PATH.
  • agent-task setup: PATH'de bulunan codex ve goose sürümlerini yazdırır.
  • get-task: A script for the coding agent to retrieve its current task instructions.
  • get-task: Kodlama ajanının mevcut görev talimatlarını almasını sağlayan bir betik.
  • start-work: A helper that configures a freshly checked-out repository for development.
  • start-work: Yeni klonlanmış bir depoyu geliştirme için yapılandıran bir yardımcı.
  • download-internet-resources: A helper script that scans task descriptions for URLs and downloads them (or clones Git repositories) for offline access.
  • download-internet-resources: Görev tanımlarını URL'ler için tarayan ve çevrimdışı erişim için indiren (veya Git depolarını klonlayan) bir yardımcı betik.

FeaturesÖzellikler

Secure Sandbox Environment

Güvenli Sanal Alan Ortamı

Run AI agents in isolated sandboxes with controlled network access and resource limits.

Yapay zeka ajanlarını, kontrollü ağ erişimi ve kaynak sınırları olan izole sanal alanlarda çalıştırın.

Real-time Recording

Gerçek Zamanlı Kayıt

Record and replay agent sessions with the built-in recording system.

Dahili kayıt sistemi ile ajan oturumlarını kaydedin ve yeniden oynatın.

Mock API Server

Mock API Sunucusu

Test your agents with mock APIs and predefined scenarios.

Ajanlarınızı mock API'lar ve önceden tanımlanmış senaryolarla test edin.

Multi-Language Support

Çoklu Dil Desteği

Works with any programming language and development environment.

Herhangi bir programlama dili ve geliştirme ortamıyla uyumludur.

Localhost Networking

Localhost Ağ Desteği

Secure localhost networking support for development environments.

Geliştirme ortamları için güvenli localhost ağ desteği sunar.

Complete Audit Trail

Tam Denetim İzi

Every task and its solution are recorded in your git history.

Her görev ve çözümü, Git geçmişinize kaydedilir.

Multi-Platform SupportÇoklu Platform Desteği

Agent Harbor works seamlessly across different platforms and interfaces.

Agent Harbor, farklı platformlar ve arayüzler arasında sorunsuz bir şekilde çalışır.

Desktop Application

Masaüstü Uygulaması

Native Electron desktop app with full GUI support.

Tam GUI desteğine sahip yerel Electron masaüstü uygulaması.

Terminal Interface (TUI)

Terminal Arayüzü (TUI)

Rich terminal user interface for command-line workflows.

Komut satırı iş akışları için zengin terminal kullanıcı arayüzü.

Web UI

Web Arayüzü

Modern web interface accessible from any browser.

Herhangi bir tarayıcıdan erişilebilen modern web arayüzü.

macOS Native

macOS Yerel Uygulaması

Native macOS application with Xcode integration.

Xcode entegrasyonu ile yerel macOS uygulaması.

Development Containers

Geliştirme Konteynerleri

Dev container support for consistent development environments.

Tutarlı geliştirme ortamları için dev container desteği.

IDE Integration

IDE Entegrasyonu

VSCode and Vim SDKs for seamless IDE integration.

Sorunsuz IDE entegrasyonu için VSCode ve Vim SDK'ları.

Supported AI AssistantsDesteklenen YZ Asistanları

Agent Harbor works with all major AI coding assistants, providing a unified interface regardless of which one you use.

Agent Harbor, tüm önde gelen yapay zeka kodlama asistanlarıyla çalışır ve hangisini kullanırsanız kullanın birleşik bir arayüz sunar.

GitHub Copilot

Your AI pair programmer

Yapay zeka çift programcınız

Claude Code

Advanced code generation

Gelişmiş kod üretimi

OpenAI Codex

Powerful code understanding

Güçlü kod anlama

Jules

Google's coding assistant

Google'ın kodlama asistanı

Goose

Square's AI development tool

Square'in yapay zeka aracı

OpenHands

Open-source AI assistant

Açık kaynaklı YZ asistanı

Setup InstructionsKurulum Talimatları

Codex

In your Codex environment's Advanced settings, enter the following setup script:

Codex ortamınızın Gelişmiş ayarlarında, aşağıdaki kurulum betiğini girin:

# Clone Agent Harbor repository and run setup
git clone https://github.com/blocksense-network/agent-harbor
agent-harbor/codex-setup

Jules

In the Jules web-interface, select a codebase in the left-hand-side panel, click "Configuration" and enter the following Initial Script:

Jules web arayüzünde, sol panelden bir kod tabanı seçin, "Configuration"a tıklayın ve aşağıdaki Başlangıç Betiğini girin:

# Clone Agent Harbor repository and run setup
git clone https://github.com/blocksense-network/agent-harbor
agent-harbor/codex-setup

Goose

TBD - Usage instructions for Goose will be added once integration is tested.

Belirlenecek - Goose için kullanım talimatları, entegrasyon test edildikten sonra eklenecektir.

Open Hands

TBD - Usage instructions for Open Hands will be added once integration is tested.

Belirlenecek - Open Hands için kullanım talimatları, entegrasyon test edildikten sonra eklenecektir.

GitHub Copilot

TBD - Usage instructions for GitHub Copilot will be added once integration is tested.

Belirlenecek - GitHub Copilot için kullanım talimatları, entegrasyon test edildikten sonra eklenecektir.

Setup ArchitectureKurulum Mimarisi

Agent Harbor uses a three-phase setup process for AI agents, allowing for shared and specific configurations.

Agent Harbor, yapay zeka ajanları için paylaşılan ve ajana özel yapılandırmalara olanak tanıyan üç aşamalı bir kurulum süreci kullanır.

1

common-pre-setup

ortak-ön-kurulum

Runs first, handles shared initializations across all agents.

İlk olarak çalışır, tüm ajanlar için ortak başlatmaları yönetir.

2

{agent}-setup

{ajan}-kurulum

Runs second, configures agent-specific settings.

İkinci olarak çalışır, ajana özel ayarları yapılandırır.

3

common-post-setup

ortak-son-kurulum

Runs last, performs finalization tasks.

Son olarak çalışır, sonlandırma görevlerini yerine getirir.

Environment VariablesOrtam Değişkenleri

Configure Agent Harbor behavior using environment variables.

Agent Harbor'ın davranışını ortam değişkenleri kullanarak yapılandırın.

NIX

Set to 1 to enable Nix installation during common-pre-setup.

Ortak ön kurulum sırasında Nix kurulumunu etkinleştirmek için değeri 1 yapın.

# Enable Nix
NIX=1

DEV_SHELLGELİŞTİRME_SHELL'i

Used via @agents-setup directives to specify the Nix development shell.

Nix geliştirme kabuğunu belirtmek için @agents-setup direktifleri aracılığıyla kullanılır.

# Specify Nix shell
@agent-setup DEV_SHELL=csharp

TESTED_COMPONENTSTEST_EDİLECEK_BİLEŞENLER

Used via @agents-setup directives to append components for testing.

Test edilecek bileşenleri eklemek için @agents-setup direktifleri aracılığıyla kullanılır.

# Add components
@agent-setup TESTED_COMPONENTS+=backend,db

Minimal Example ProjectBasit Örnek Proje

Here's a minimal example project structure to get started with Agent Harbor:

Agent Harbor'a başlamak için basit bir örnek proje yapısı:

Project StructureProje Yapısı

# Minimal Agent Harbor Project Structure
minimal-agent-harbor-project/
├── .agents/
│ ├── tasks/ # Agent task definitions
│ ├── workflows/ # Workflow commands
│ └── setup/ # Setup scripts
├── src/
│ └── main.js # Main application code
├── tests/
│ └── test_scenario_integration.js
├── package.json # Project dependencies
└── README.md # Project documentation

Quick Start CommandsHızlı Başlangıç Komutları

# Start project with Agent Harbor
agent-task minimal-project-setup

# Create a simple API endpoint task
agent-task --prompt="Create a simple API endpoint with Express.js" api-feature

# AI agent gets the task and works on it
get-task

# Check setup environment
get-task --get-setup-env

Example Task DescriptionÖrnek Görev Tanımı

# Task: Create User Authentication API
Implement user authentication with JWT tokens.
Include login, logout and password reset functions.
Write tests for all endpoints.

# Use workflow command for frontend integration
/frontend-integration

# Setup directives
@agent-setup DEV_SHELL=nodejs
@agent-setup TESTED_COMPONENTS+=api,auth

Expected ResultsBeklenen Sonuçlar

  • Complete API implementation with authentication
  • Kimlik doğrulama özelliğine sahip eksiksiz API uygulaması
  • Automated test suite
  • Otomatikleştirilmiş test paketi
  • Git history with task descriptions
  • Görev tanımlarını içeren Git geçmişi
  • Ready-to-merge pull request
  • Birleştirmeye hazır pull request

Future DirectionGeleceğe Bakış

Agent Harbor aims to further automate the interaction between developers and AI agents.

Agent Harbor, geliştiriciler ve yapay zeka ajanları arasındaki etkileşimi daha da otomatikleştirmeyi hedeflemektedir.

Automation via APIAPI ile Otomasyon

  • An API integration with Codex (and potentially others) could automate the get-task prompt step.
  • Codex (ve potansiyel olarak diğerleri) ile bir API entegrasyonu, get-task istemi adımını otomatikleştirebilir.

Browser Extension IntegrationTarayıcı Eklentisi Entegrasyonu

  • (Interim) A browser extension could drive the Codex WebUI to trigger the initial task.
  • (Ara Çözüm) Bir tarayıcı eklentisi, ilk görevi tetiklemek için Codex Web Arayüzünü yönlendirebilir.