aiko 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4d6bb00af4ebfc5d2758c6c65bf67f79d1676f6f1d84ca6c71bd926afa05a5ee
+  data.tar.gz: 27fd6ead4d6c6bb6e315188be9a2fa1cddbad6153155d27762a453b815d04d4f
+SHA512:
+  metadata.gz: 547a3023dd19bfc0b6f2491d5fc0705f2f4dfd6b6747221a13ca6c2124f43169735e4b96c4dc8d606cf8092f11393ec3ff3a31949caa6ac903e842df1359ad03
+  data.tar.gz: 6e7219dec3d1a0b0d061527a726845b5de4d7ae5db77016b76d31e97c77da5cdc1367b5b6b1937701f8b97e511c4eb448bb77e8923bf082f548e5785c8687ac6

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Satoshi Takei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.ja.md

@@ -0,0 +1,68 @@
+# aiko
+
+[English README](README.md)
+
+AI + coding. OpenAI互換LLM API（DeepSeek / OpenRouter等）で動くRuby製CLIコーディングエージェント。
+LLMにファイル操作・コマンド実行・検索のツールを与え、エージェントループで自律的にコーディングタスクを実行します。
+
+> 名前の由来は「AI + コーディング」。「コーディング」の「コ」を取って、AI + ko = aiko です。
+
+## インストール
+
+```sh
+bundle install
+rake install   # gemをビルドしてローカルインストール（aikoコマンドが使えるようになる）
+```
+
+## 設定
+
+APIキーは環境変数で設定します（設定ファイルには書けません）。
+
+```sh
+# DeepSeek本家（デフォルト。deepseek-v4-flashを使用）
+export AIKO_API_KEY=sk-...
+
+# OpenRouterを使う場合（例: より高性能なdeepseek-v4-pro）
+export AIKO_API_KEY=sk-or-...
+export AIKO_BASE_URL=https://openrouter.ai/api/v1
+export AIKO_MODEL=deepseek/deepseek-v4-pro
+```
+
+任意で `~/.aiko/config.json` に `base_url` / `model` / `max_iterations` を設定できます。
+優先順位は「コマンドラインオプション > 環境変数 > 設定ファイル > デフォルト」です。
+
+## 使い方
+
+```sh
+# ワンショット: プロンプトを1回処理して終了
+aiko "fizzbuzz.rb を作成し、実行して動作確認してください"
+
+# REPL: 対話モード（/help でコマンド一覧、/exit で終了）
+aiko
+
+# 主要オプション
+aiko -y "..."             # すべてのツール実行を自動承認
+aiko -w DIR "..."         # 作業ディレクトリを指定
+aiko -m MODEL "..."       # モデル名を上書き
+aiko --max-iterations 30  # エージェントループの上限回数
+```
+
+ファイル書き込み・編集・コマンド実行の前にはユーザー承認を求めます。
+
+> **警告**: `-y` / `--yes` はLLMが提案したファイル書き込みやシェルコマンドを確認なしで実行します。
+> 内容を確認できない操作が無条件に実行されるため、利用は自己責任で、信頼できる作業ディレクトリでのみ使用してください。
+
+## 開発
+
+```sh
+rake test                 # テスト実行（デフォルトタスク）
+rake run -- -y "..."      # インストールせずに動作確認
+```
+
+仕様は [doc/spec/](doc/spec/01_overview.md)、実装手順は [doc/implementation/](doc/implementation/00_README.md) を参照。
+
+## 作者
+
+Satoshi Takei — [GitHub @takeisa](https://github.com/takeisa) / [X @takeisa](https://x.com/takeisa)
+
+AIコーディングエージェントを利用して開発しています。設計・実装の記録は [doc/](doc/spec/01_overview.md) を参照。

data/README.md

@@ -0,0 +1,69 @@
+# aiko
+
+[日本語版 README](README.ja.md)
+
+AI + coding. A Ruby CLI coding agent that runs on OpenAI-compatible LLM APIs (DeepSeek, OpenRouter, etc.).
+It gives the LLM tools for file operations, command execution, and search, and carries out coding tasks autonomously through an agent loop.
+
+> The name comes from "AI + コーディング (coding)" — taking "コ" (ko), the first syllable of コーディング, gives AI + ko = aiko.
+
+## Installation
+
+```sh
+bundle install
+rake install   # build the gem and install it locally (makes the `aiko` command available)
+```
+
+## Configuration
+
+The API key is set via an environment variable (it cannot be set in a config file).
+
+```sh
+# DeepSeek (default; uses deepseek-v4-flash)
+export AIKO_API_KEY=sk-...
+
+# Using OpenRouter (e.g. the more capable deepseek-v4-pro)
+export AIKO_API_KEY=sk-or-...
+export AIKO_BASE_URL=https://openrouter.ai/api/v1
+export AIKO_MODEL=deepseek/deepseek-v4-pro
+```
+
+Optionally, you can set `base_url` / `model` / `max_iterations` in `~/.aiko/config.json`.
+The precedence is: command-line options > environment variables > config file > defaults.
+
+## Usage
+
+```sh
+# One-shot: process a single prompt and exit
+aiko "Create fizzbuzz.rb, run it, and verify it works"
+
+# REPL: interactive mode (/help for command list, /exit to quit)
+aiko
+
+# Main options
+aiko -y "..."             # auto-approve all tool executions
+aiko -w DIR "..."         # specify working directory
+aiko -m MODEL "..."       # override the model name
+aiko --max-iterations 30  # cap the number of agent loop iterations
+```
+
+aiko asks for your approval before writing/editing files or running commands.
+
+> **Warning**: `-y` / `--yes` runs file writes/edits and shell commands proposed by the LLM
+> without confirmation. Since operations you cannot review will run unconditionally,
+> use this at your own risk, and only in a directory you trust.
+
+## Development
+
+```sh
+rake test                 # run tests (default task)
+rake run -- -y "..."      # try it out without installing
+```
+
+See [doc/spec/](doc/spec/01_overview.md) for the specification and [doc/implementation/](doc/implementation/00_README.md) for the implementation notes.
+
+## Author
+
+Satoshi Takei — [GitHub @takeisa](https://github.com/takeisa) / [X @takeisa](https://x.com/takeisa)
+
+Developed using an AI coding agent. See [doc/](doc/spec/01_overview.md) for the design and implementation notes.

data/exe/aiko

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "aiko"
+exit Aiko::CLI.start(ARGV)

data/lib/aiko/agent.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Aiko
+  class Agent
+    MAX_ITERATIONS_MESSAGE = "(最大ループ回数に達したため処理を打ち切りました)"
+
+    attr_reader :conversation
+
+    def initialize(llm:, registry:, callbacks:, conversation:, max_iterations: 20)
+      @llm = llm
+      @registry = registry
+      @callbacks = callbacks
+      @conversation = conversation
+      @max_iterations = max_iterations
+    end
+
+    def run(user_input)
+      @conversation.add_user(user_input)
+      @max_iterations.times do
+        response = request_completion
+        return final_answer(response) unless response.tool_calls?
+
+        report_progress(response)
+        execute_tool_calls(response.tool_calls)
+      end
+      @callbacks.on_assistant_text(MAX_ITERATIONS_MESSAGE)
+      MAX_ITERATIONS_MESSAGE
+    end
+
+    private
+
+    def request_completion
+      @callbacks.on_request_start
+      response = begin
+        @llm.chat(messages: @conversation.messages, tools: @registry.schemas)
+      ensure
+        @callbacks.on_request_end
+      end
+      @conversation.add_assistant(response.raw_message)
+      response
+    end
+
+    def final_answer(response)
+      @callbacks.on_assistant_text(response.content)
+      response.content
+    end
+
+    def report_progress(response)
+      @callbacks.on_assistant_text(response.content) unless response.content.empty?
+    end
+
+    def execute_tool_calls(tool_calls)
+      tool_calls.each do |tool_call|
+        @callbacks.on_tool_start(tool_call.name, tool_call.arguments)
+        result = execute_tool_call(tool_call)
+        @callbacks.on_tool_result(tool_call.name, result)
+        @conversation.add_tool_result(tool_call_id: tool_call.id, content: result)
+      end
+    end
+
+    def execute_tool_call(tool_call)
+      if tool_call.parse_error
+        "Error: invalid tool arguments JSON: #{tool_call.parse_error}"
+      else
+        @registry.dispatch(tool_call.name, tool_call.arguments, callbacks: @callbacks)
+      end
+    end
+  end
+end

data/lib/aiko/cli.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Aiko
+  class CLI
+    REPL_HELP = <<~HELP
+      /exit, /quit  終了 (Ctrl-D も同様)
+      /clear        会話履歴をクリア
+      /help         このヘルプを表示
+    HELP
+
+    def self.start(argv)
+      new.start(argv)
+    end
+
+    def self.parse(argv)
+      options = {}
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: aiko [options] [prompt]"
+        opts.on("-w", "--workdir DIR", "Working directory (default: current directory)") { |v| options[:workdir] = v }
+        opts.on("-m", "--model MODEL", "Override model name") { |v| options[:model] = v }
+        opts.on("--base-url URL", "Override API endpoint") { |v| options[:base_url] = v }
+        opts.on("-y", "--yes", "Auto-approve all tool executions") { options[:yes] = true }
+        opts.on("--max-iterations N", Integer, "Max agent loop iterations (default: 20)") { |v| options[:max_iterations] = v }
+        opts.on("-v", "--version", "Show version") { options[:version] = true }
+        opts.on("-h", "--help", "Show help") { options[:help] = true }
+      end
+      rest = parser.parse(argv)
+      options[:help_text] = parser.to_s
+      prompt = rest.empty? ? nil : rest.join(" ")
+      [options, prompt]
+    end
+
+    def start(argv)
+      options, prompt = self.class.parse(argv)
+      return show_version if options[:version]
+      return show_help(options) if options[:help]
+
+      config = Config.load(config_options(options))
+      ui = UI.new(auto_approve: options.fetch(:yes, false))
+      agent = build_agent(config, ui)
+      prompt ? run_oneshot(agent, ui, prompt) : run_repl(agent, ui, config)
+    rescue OptionParser::ParseError, ConfigError => e
+      warn "Error: #{e.message}"
+      2
+    end
+
+    private
+
+    def config_options(options)
+      options.slice(:workdir, :model, :base_url, :max_iterations)
+    end
+
+    def show_version
+      puts "aiko #{VERSION}"
+      0
+    end
+
+    def show_help(options)
+      puts options[:help_text]
+      0
+    end
+
+    def build_agent(config, ui)
+      registry = Tools::Registry.new
+      [Tools::ReadFile, Tools::WriteFile, Tools::EditFile,
+       Tools::ListFiles, Tools::RunCommand, Tools::Search].each do |klass|
+        registry.register(klass.new(workdir: config.workdir))
+      end
+      llm = LLM::OpenAICompatible.new(
+        api_key: config.api_key, base_url: config.base_url, model: config.model
+      )
+      conversation = Conversation.new(system_prompt: SystemPrompt.build(workdir: config.workdir))
+      Agent.new(llm: llm, registry: registry, callbacks: ui,
+                conversation: conversation, max_iterations: config.max_iterations)
+    end
+
+    def run_oneshot(agent, ui, prompt)
+      agent.run(prompt)
+      0
+    rescue LLM::APIError => e
+      ui.show_error(e.message)
+      1
+    rescue Interrupt
+      130
+    end
+
+    def run_repl(agent, ui, config)
+      require "reline"
+      ui.puts "aiko #{VERSION} | model: #{config.model} | workdir: #{config.workdir}"
+      ui.puts "Type /help for commands, /exit to quit."
+      loop do
+        line = read_line
+        break if line.nil?
+
+        line = line.strip
+        next if line.empty?
+
+        if line.start_with?("/")
+          break if %w[/exit /quit].include?(line)
+
+          handle_repl_command(agent, ui, line)
+        else
+          run_repl_turn(agent, ui, line)
+        end
+      end
+      0
+    end
+
+    def read_line
+      Reline.readline("> ", true)
+    rescue Interrupt
+      ""
+    end
+
+    def handle_repl_command(agent, ui, line)
+      case line
+      when "/clear"
+        agent.conversation.clear
+        ui.puts "(会話履歴をクリアしました)"
+      when "/help"
+        ui.puts REPL_HELP
+      else
+        ui.show_error("unknown command: #{line} (/help で一覧を表示)")
+      end
+    end
+
+    def run_repl_turn(agent, ui, line)
+      agent.run(line)
+    rescue Interrupt
+      ui.puts "(中断しました)"
+    rescue LLM::APIError => e
+      ui.show_error(e.message)
+    end
+  end
+end

data/lib/aiko/config.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Aiko
+  class Config
+    DEFAULTS = {
+      base_url: "https://api.deepseek.com",
+      model: "deepseek-v4-flash",
+      max_iterations: 20
+    }.freeze
+
+    FILE_KEYS = %w[base_url model max_iterations].freeze
+
+    attr_reader :api_key, :base_url, :model, :max_iterations, :workdir
+
+    def self.load(cli_options = {}, config_path: default_config_path, env: ENV)
+      file = load_file(config_path)
+      merged = DEFAULTS.dup
+      FILE_KEYS.each do |key|
+        merged[key.to_sym] = file[key] if file.key?(key)
+      end
+      merged[:base_url] = env["AIKO_BASE_URL"] if env["AIKO_BASE_URL"]
+      merged[:model] = env["AIKO_MODEL"] if env["AIKO_MODEL"]
+      merged[:api_key] = env["AIKO_API_KEY"]
+      %i[api_key base_url model max_iterations workdir].each do |key|
+        merged[key] = cli_options[key] if cli_options.key?(key) && !cli_options[key].nil?
+      end
+      new(**merged)
+    end
+
+    def self.default_config_path
+      File.join(Dir.home, ".aiko", "config.json")
+    end
+
+    def self.load_file(path)
+      return {} unless File.exist?(path)
+
+      JSON.parse(File.read(path))
+    rescue JSON::ParserError => e
+      raise ConfigError, "invalid JSON in config file #{path}: #{e.message}"
+    end
+    private_class_method :load_file
+
+    def initialize(api_key:, base_url:, model:, max_iterations:, workdir: nil)
+      @api_key = api_key
+      @base_url = base_url
+      @model = model
+      @max_iterations = max_iterations
+      @workdir = File.expand_path(workdir || Dir.pwd)
+      validate!
+    end
+
+    private
+
+    def validate!
+      raise ConfigError, "API key is not set (set AIKO_API_KEY)" if @api_key.nil? || @api_key.empty?
+      raise ConfigError, "base_url must start with http:// or https://: #{@base_url}" unless %r{\Ahttps?://}.match?(@base_url)
+      unless @max_iterations.is_a?(Integer) && @max_iterations.positive?
+        raise ConfigError, "max_iterations must be a positive integer: #{@max_iterations.inspect}"
+      end
+    end
+  end
+end

data/lib/aiko/conversation.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Aiko
+  class Conversation
+    attr_reader :messages
+
+    def initialize(system_prompt:)
+      @system_prompt = system_prompt
+      @messages = [{ "role" => "system", "content" => system_prompt }]
+    end
+
+    def add_user(text)
+      @messages << { "role" => "user", "content" => text }
+    end
+
+    def add_assistant(message)
+      @messages << message
+    end
+
+    def add_tool_result(tool_call_id:, content:)
+      @messages << { "role" => "tool", "tool_call_id" => tool_call_id, "content" => content }
+    end
+
+    def clear
+      @messages = [{ "role" => "system", "content" => @system_prompt }]
+    end
+  end
+end

data/lib/aiko/errors.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Aiko
+  class Error < StandardError; end
+  class ConfigError < Error; end
+
+  module LLM
+    class APIError < Error; end
+  end
+
+  module Tools
+    class ToolError < Error; end
+  end
+end

data/lib/aiko/llm/client.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Aiko
+  module LLM
+    class Client
+      # messages: OpenAI互換形式のメッセージ配列
+      # tools:    OpenAI互換形式のツール定義配列（空配列可）
+      # 戻り値:   Aiko::LLM::Response
+      def chat(messages:, tools: [])
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/aiko/llm/openai_compatible.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Aiko
+  module LLM
+    class OpenAICompatible < Client
+      OPEN_TIMEOUT = 10
+      READ_TIMEOUT = 300
+      RETRY_WAITS = [1, 4].freeze
+
+      def initialize(api_key:, base_url:, model:, sleeper: ->(sec) { sleep(sec) })
+        super()
+        @api_key = api_key
+        @endpoint = URI.parse("#{base_url.sub(%r{/+\z}, "")}/chat/completions")
+        @model = model
+        @sleeper = sleeper
+      end
+
+      def chat(messages:, tools: [])
+        body = { "model" => @model, "messages" => messages }
+        body["tools"] = tools unless tools.empty?
+
+        status, response_body = post_with_retry(body)
+        unless (200..299).cover?(status)
+          raise APIError, "API request failed with status #{status}: #{response_body.to_s[0, 500]}"
+        end
+
+        to_response(parse_json(response_body))
+      end
+
+      private
+
+      def post_with_retry(body)
+        status, response_body = post_json(body)
+        RETRY_WAITS.each do |wait|
+          break unless status == 429 || (500..599).cover?(status)
+
+          @sleeper.call(wait)
+          status, response_body = post_json(body)
+        end
+        [status, response_body]
+      end
+
+      # テストではこのメソッドをオーバーライドしてHTTPをスタブする
+      def post_json(body)
+        http = Net::HTTP.new(@endpoint.host, @endpoint.port)
+        http.use_ssl = @endpoint.scheme == "https"
+        http.open_timeout = OPEN_TIMEOUT
+        http.read_timeout = READ_TIMEOUT
+
+        request = Net::HTTP::Post.new(@endpoint.request_uri)
+        request["Authorization"] = "Bearer #{@api_key}"
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate(body)
+
+        response = http.request(request)
+        [response.code.to_i, response.body]
+      rescue Net::OpenTimeout, Net::ReadTimeout, SystemCallError, OpenSSL::SSL::SSLError => e
+        raise APIError, "API request failed: #{e.class}: #{e.message}"
+      end
+
+      def parse_json(body)
+        JSON.parse(body)
+      rescue JSON::ParserError => e
+        raise APIError, "invalid JSON response: #{e.message}"
+      end
+
+      def to_response(json)
+        message = json.dig("choices", 0, "message")
+        raise APIError, "response has no choices: #{json.inspect[0, 500]}" unless message
+
+        Response.new(
+          content: message["content"],
+          tool_calls: (message["tool_calls"] || []).map { |tc| to_tool_call(tc) },
+          raw_message: message,
+          usage: json["usage"] || {}
+        )
+      end
+
+      def to_tool_call(tool_call)
+        function = tool_call.fetch("function", {})
+        arguments = JSON.parse(function["arguments"].to_s)
+        arguments = {} unless arguments.is_a?(Hash)
+        ToolCall.new(id: tool_call["id"], name: function["name"], arguments: arguments)
+      rescue JSON::ParserError => e
+        ToolCall.new(id: tool_call["id"], name: function["name"], arguments: {},
+                     parse_error: e.message)
+      end
+    end
+  end
+end

data/lib/aiko/llm/response.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Aiko
+  module LLM
+    class ToolCall
+      attr_reader :id, :name, :arguments, :parse_error
+
+      def initialize(id:, name:, arguments:, parse_error: nil)
+        @id = id
+        @name = name
+        @arguments = arguments
+        @parse_error = parse_error
+        freeze
+      end
+    end
+
+    class Response
+      attr_reader :content, :tool_calls, :raw_message, :usage
+
+      def initialize(content:, tool_calls: [], raw_message: {}, usage: {})
+        @content = content.to_s
+        @tool_calls = tool_calls
+        @raw_message = raw_message
+        @usage = usage
+        freeze
+      end
+
+      def tool_calls?
+        !tool_calls.empty?
+      end
+    end
+  end
+end

data/lib/aiko/system_prompt.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Aiko
+  module SystemPrompt
+    def self.build(workdir:)
+      <<~PROMPT
+        You are aiko, a coding agent that works in the user's project directory.
+        You accomplish tasks by calling the provided tools (reading/writing/editing
+        files, listing files, searching, and running shell commands).
+
+        Working directory: #{workdir}
+        All relative paths are resolved from this directory. You cannot access
+        files outside of it.
+
+        Guidelines for tool use:
+        - Read a file before you edit or overwrite it.
+        - Prefer edit_file for small changes and write_file for new files or rewrites.
+        - You may run commands to inspect the environment and to verify your work
+          (e.g. run the tests or execute the program you just wrote).
+        - If a tool returns an error, read it carefully and correct your approach.
+
+        Answer style:
+        - Be concise. After completing a task, summarize what you did and the result.
+        - Reply in the same language the user writes in.
+      PROMPT
+    end
+  end
+end