MessagesAlat

Alat Bash

Fitur ini memenuhi syarat untuk Zero Data Retention (ZDR). Ketika organisasi Anda memiliki pengaturan ZDR, data yang dikirim melalui fitur ini tidak disimpan setelah respons API dikembalikan.

Alat bash memungkinkan Claude untuk mengeksekusi perintah shell dalam sesi bash yang persisten, memungkinkan operasi sistem, eksekusi skrip, dan otomatisasi baris perintah. Akses shell adalah kemampuan agen yang fundamental. Pada Terminal-Bench 2.0, sebuah benchmark yang mengevaluasi tugas terminal dunia nyata menggunakan validasi berbasis shell saja, Claude menunjukkan peningkatan performa yang kuat dengan akses ke sesi bash yang persisten.

Ikhtisar

Alat bash menyediakan Claude dengan:

Sesi bash persisten yang mempertahankan state
Kemampuan untuk menjalankan perintah shell apa pun
Akses ke variabel lingkungan dan direktori kerja
Kemampuan perangkaian perintah dan scripting

Untuk dukungan model, lihat Referensi alat.

Kasus penggunaan

Alur kerja pengembangan: Menjalankan perintah build, pengujian, dan alat pengembangan
Otomatisasi sistem: Mengeksekusi skrip, mengelola file, mengotomatisasi tugas
Pemrosesan data: Memproses file, menjalankan skrip analisis, mengelola dataset
Penyiapan lingkungan: Menginstal paket, mengonfigurasi lingkungan

Mulai cepat

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[{"type": "bash_20250124", "name": "bash"}],
    messages=[
        {"role": "user", "content": "List all Python files in the current directory."}
    ],
)

print(response)

Cara kerjanya

Alat bash mempertahankan sesi yang persisten:

Claude menentukan perintah apa yang akan dijalankan
Anda mengeksekusi perintah tersebut dalam shell bash
Kembalikan output (stdout dan stderr) ke Claude
State sesi tetap bertahan di antara perintah (variabel lingkungan, direktori kerja)

Parameter

Parameter	Wajib	Deskripsi
`command`	Ya*	Perintah bash yang akan dijalankan
`restart`	Tidak	Atur ke `true` untuk memulai ulang sesi bash

*Wajib kecuali menggunakan restart

Contoh: Otomatisasi multi-langkah

Claude dapat merangkai perintah untuk menyelesaikan tugas yang kompleks:

User request:
"Install the requests library and create a simple Python script that
fetches a joke from an API, then run it."

Claude's tool uses:
1. Install package
   {"command": "pip install requests"}

2. Create script
   {"command": "cat > fetch_joke.py << 'EOF'\nimport requests\nresponse = requests.get('https://official-joke-api.appspot.com/random_joke')\njoke = response.json()\nprint(f\"Setup: {joke['setup']}\")\nprint(f\"Punchline: {joke['punchline']}\")\nEOF"}

3. Run script
   {"command": "python fetch_joke.py"}

Sesi mempertahankan state di antara perintah, sehingga file yang dibuat pada langkah 2 tersedia pada langkah 3.

Mengimplementasikan alat bash

Alat bash diimplementasikan sebagai alat tanpa skema. Saat menggunakan alat ini, Anda tidak perlu menyediakan skema input seperti pada alat lainnya; skema sudah terintegrasi ke dalam model Claude dan tidak dapat dimodifikasi.

Siapkan lingkungan bash

Buat sesi bash persisten yang dapat berinteraksi dengan Claude:

import subprocess
import threading
import queue


class BashSession:
    def __init__(self):
        self.process = subprocess.Popen(
            ["/bin/bash"],
            stdin=subprocess.PIPE,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True,
            bufsize=0,
        )
        self.output_queue = queue.Queue()
        self.error_queue = queue.Queue()
        self._start_readers()

Tangani eksekusi perintah

Buat fungsi untuk mengeksekusi perintah dan menangkap output:

def execute_command(self, command):
    # Kirim perintah ke bash
    self.process.stdin.write(command + "\n")
    self.process.stdin.flush()

    # Tangkap output dengan timeout
    output = self._read_output(timeout=10)
    return output

Proses panggilan alat dari Claude

Ekstrak dan eksekusi perintah dari respons Claude:

for content in response.content:
    if content.type == "tool_use" and content.name == "bash":
        if content.input.get("restart"):
            bash_session.restart()
            result = "Bash session restarted"
        else:
            command = content.input.get("command")
            result = bash_session.execute_command(command)

        # Kembalikan hasil ke Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result,
        }

Implementasikan langkah-langkah keamanan

Tambahkan validasi dan pembatasan. Gunakan allowlist (daftar izin) daripada blocklist (daftar blokir), karena blocklist mudah dilewati. Tolak operator shell agar perintah berantai tidak dapat lolos dari allowlist:

import shlex

ALLOWED_COMMANDS = {"ls", "cat", "echo", "pwd", "grep", "find", "wc", "head", "tail"}
SHELL_OPERATORS = {"&&", "||", "|", ";", "&", ">", "<", ">>"}


def validate_command(command):
    # Izinkan hanya perintah dari allowlist eksplisit
    try:
        tokens = shlex.split(command)
    except ValueError:
        return False, "Could not parse command"

    if not tokens:
        return False, "Empty command"

    executable = tokens[0]
    if executable not in ALLOWED_COMMANDS:
        return False, f"Command '{executable}' is not in the allowlist"

    # Tolak operator shell yang akan merangkai perintah tambahan
    for token in tokens[1:]:
        if token in SHELL_OPERATORS or token.startswith(("$", "`")):
            return False, f"Shell operator '{token}' is not allowed"

    return True, None

Pemeriksaan ini adalah garis pertahanan pertama. Untuk isolasi yang lebih kuat, jalankan perintah yang telah divalidasi dengan shell=False dan berikan shlex.split(command) sebagai daftar argumen, sehingga shell tidak pernah menginterpretasikan string tersebut.

Menangani error

Saat mengimplementasikan alat bash, tangani berbagai skenario error:

Ikuti praktik terbaik implementasi

Keamanan

Alat bash menyediakan akses sistem langsung. Implementasikan langkah-langkah keamanan penting berikut:

Menjalankan dalam lingkungan terisolasi (Docker/VM)
Mengimplementasikan pemfilteran perintah dan allowlist
Menetapkan batas sumber daya (CPU, memori, disk)
Mencatat semua perintah yang dieksekusi

Rekomendasi utama

Gunakan ulimit untuk menetapkan batasan sumber daya
Filter perintah berbahaya (sudo, rm -rf, dll.)
Jalankan dengan izin pengguna minimal
Pantau dan catat semua eksekusi perintah

Harga

Alat bash menambahkan 245 token input ke panggilan API Anda.

Token tambahan dikonsumsi oleh:

Output perintah (stdout/stderr)
Pesan kesalahan
Konten file berukuran besar

Lihat harga penggunaan alat untuk detail harga lengkap.

Pola umum

Alur kerja pengembangan

Menjalankan pengujian: pytest && coverage report
Membangun proyek: npm install && npm run build
Operasi Git: git status && git add . && git commit -m "message"

Checkpointing berbasis Git

Git berfungsi sebagai mekanisme pemulihan terstruktur dalam alur kerja agen yang berjalan lama, bukan hanya cara untuk menyimpan perubahan:

Tangkap baseline: Sebelum pekerjaan agen dimulai, commit state saat ini. Ini adalah titik awal yang diketahui baik.
Commit per fitur: Setiap fitur yang selesai mendapatkan commit-nya sendiri. Ini berfungsi sebagai titik rollback jika terjadi kesalahan di kemudian hari.
Rekonstruksi state di awal sesi: Baca git log bersama dengan file progres untuk memahami apa yang sudah dilakukan dan apa yang akan dilakukan selanjutnya.
Revert saat gagal: Jika pekerjaan menyimpang, git checkout mengembalikan ke commit baik terakhir alih-alih mencoba men-debug state yang rusak.

Operasi file

Memproses data: wc -l *.csv && ls -lh *.csv
Mencari file: find . -name "*.py" | xargs grep "pattern"
Membuat backup: tar -czf backup.tar.gz ./data

Tugas sistem

Memeriksa sumber daya: df -h && free -m
Manajemen proses: ps aux | grep python
Penyiapan lingkungan: export PATH=$PATH:/new/path && echo $PATH

Keterbatasan

Tidak ada perintah interaktif: Tidak dapat menangani vim, less, atau prompt kata sandi
Tidak ada aplikasi GUI: Hanya baris perintah
Cakupan sesi: State sesi bash berada di sisi klien. API bersifat stateless. Aplikasi Anda bertanggung jawab untuk mempertahankan sesi shell di antara giliran.
Batas output: Output besar mungkin dipotong
Tidak ada streaming: Hasil dikembalikan setelah selesai

Menggabungkan dengan alat lain

Alat bash paling kuat ketika digabungkan dengan text editor dan alat lainnya.

Jika Anda juga menggunakan alat code execution, Claude memiliki akses ke dua lingkungan eksekusi terpisah: sesi bash lokal Anda dan container sandbox milik Anthropic. State tidak dibagikan di antara keduanya. Lihat Menggunakan code execution dengan alat eksekusi lainnya untuk panduan dalam memberikan prompt kepada Claude agar dapat membedakan antara lingkungan tersebut.

Langkah selanjutnya

Ikhtisar penggunaan alat

Pelajari tentang penggunaan alat dengan Claude

Alat text editor

Lihat dan edit file teks dengan Claude

Was this page helpful?

MessagesAlat

Alat Bash

Fitur ini memenuhi syarat untuk Zero Data Retention (ZDR). Ketika organisasi Anda memiliki pengaturan ZDR, data yang dikirim melalui fitur ini tidak disimpan setelah respons API dikembalikan.

Ikhtisar

Alat bash menyediakan Claude dengan:

Sesi bash persisten yang mempertahankan state
Kemampuan untuk menjalankan perintah shell apa pun
Akses ke variabel lingkungan dan direktori kerja
Kemampuan perangkaian perintah dan scripting

Untuk dukungan model, lihat Referensi alat.

Kasus penggunaan

Alur kerja pengembangan: Menjalankan perintah build, pengujian, dan alat pengembangan
Otomatisasi sistem: Mengeksekusi skrip, mengelola file, mengotomatisasi tugas
Pemrosesan data: Memproses file, menjalankan skrip analisis, mengelola dataset
Penyiapan lingkungan: Menginstal paket, mengonfigurasi lingkungan

Mulai cepat

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[{"type": "bash_20250124", "name": "bash"}],
    messages=[
        {"role": "user", "content": "List all Python files in the current directory."}
    ],
)

print(response)

Cara kerjanya

Alat bash mempertahankan sesi yang persisten:

Claude menentukan perintah apa yang akan dijalankan
Anda mengeksekusi perintah tersebut dalam shell bash
Kembalikan output (stdout dan stderr) ke Claude
State sesi tetap bertahan di antara perintah (variabel lingkungan, direktori kerja)

Parameter

Parameter	Wajib	Deskripsi
`command`	Ya*	Perintah bash yang akan dijalankan
`restart`	Tidak	Atur ke `true` untuk memulai ulang sesi bash

*Wajib kecuali menggunakan restart

Contoh: Otomatisasi multi-langkah

Claude dapat merangkai perintah untuk menyelesaikan tugas yang kompleks:

User request:
"Install the requests library and create a simple Python script that
fetches a joke from an API, then run it."

Claude's tool uses:
1. Install package
   {"command": "pip install requests"}

2. Create script
   {"command": "cat > fetch_joke.py << 'EOF'\nimport requests\nresponse = requests.get('https://official-joke-api.appspot.com/random_joke')\njoke = response.json()\nprint(f\"Setup: {joke['setup']}\")\nprint(f\"Punchline: {joke['punchline']}\")\nEOF"}

3. Run script
   {"command": "python fetch_joke.py"}

Sesi mempertahankan state di antara perintah, sehingga file yang dibuat pada langkah 2 tersedia pada langkah 3.

Mengimplementasikan alat bash

Siapkan lingkungan bash

Buat sesi bash persisten yang dapat berinteraksi dengan Claude:

import subprocess
import threading
import queue


class BashSession:
    def __init__(self):
        self.process = subprocess.Popen(
            ["/bin/bash"],
            stdin=subprocess.PIPE,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True,
            bufsize=0,
        )
        self.output_queue = queue.Queue()
        self.error_queue = queue.Queue()
        self._start_readers()

Tangani eksekusi perintah

Buat fungsi untuk mengeksekusi perintah dan menangkap output:

def execute_command(self, command):
    # Kirim perintah ke bash
    self.process.stdin.write(command + "\n")
    self.process.stdin.flush()

    # Tangkap output dengan timeout
    output = self._read_output(timeout=10)
    return output

Proses panggilan alat dari Claude

Ekstrak dan eksekusi perintah dari respons Claude:

for content in response.content:
    if content.type == "tool_use" and content.name == "bash":
        if content.input.get("restart"):
            bash_session.restart()
            result = "Bash session restarted"
        else:
            command = content.input.get("command")
            result = bash_session.execute_command(command)

        # Kembalikan hasil ke Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result,
        }

Implementasikan langkah-langkah keamanan

import shlex

ALLOWED_COMMANDS = {"ls", "cat", "echo", "pwd", "grep", "find", "wc", "head", "tail"}
SHELL_OPERATORS = {"&&", "||", "|", ";", "&", ">", "<", ">>"}


def validate_command(command):
    # Izinkan hanya perintah dari allowlist eksplisit
    try:
        tokens = shlex.split(command)
    except ValueError:
        return False, "Could not parse command"

    if not tokens:
        return False, "Empty command"

    executable = tokens[0]
    if executable not in ALLOWED_COMMANDS:
        return False, f"Command '{executable}' is not in the allowlist"

    # Tolak operator shell yang akan merangkai perintah tambahan
    for token in tokens[1:]:
        if token in SHELL_OPERATORS or token.startswith(("$", "`")):
            return False, f"Shell operator '{token}' is not allowed"

    return True, None

Menangani error

Saat mengimplementasikan alat bash, tangani berbagai skenario error:

Ikuti praktik terbaik implementasi

Keamanan

Alat bash menyediakan akses sistem langsung. Implementasikan langkah-langkah keamanan penting berikut:

Menjalankan dalam lingkungan terisolasi (Docker/VM)
Mengimplementasikan pemfilteran perintah dan allowlist
Menetapkan batas sumber daya (CPU, memori, disk)
Mencatat semua perintah yang dieksekusi

Rekomendasi utama

Gunakan ulimit untuk menetapkan batasan sumber daya
Filter perintah berbahaya (sudo, rm -rf, dll.)
Jalankan dengan izin pengguna minimal
Pantau dan catat semua eksekusi perintah

Harga

Alat bash menambahkan 245 token input ke panggilan API Anda.

Token tambahan dikonsumsi oleh:

Output perintah (stdout/stderr)
Pesan kesalahan
Konten file berukuran besar

Lihat harga penggunaan alat untuk detail harga lengkap.

Pola umum

Alur kerja pengembangan

Menjalankan pengujian: pytest && coverage report
Membangun proyek: npm install && npm run build
Operasi Git: git status && git add . && git commit -m "message"

Checkpointing berbasis Git

Git berfungsi sebagai mekanisme pemulihan terstruktur dalam alur kerja agen yang berjalan lama, bukan hanya cara untuk menyimpan perubahan:

Tangkap baseline: Sebelum pekerjaan agen dimulai, commit state saat ini. Ini adalah titik awal yang diketahui baik.
Commit per fitur: Setiap fitur yang selesai mendapatkan commit-nya sendiri. Ini berfungsi sebagai titik rollback jika terjadi kesalahan di kemudian hari.
Rekonstruksi state di awal sesi: Baca git log bersama dengan file progres untuk memahami apa yang sudah dilakukan dan apa yang akan dilakukan selanjutnya.
Revert saat gagal: Jika pekerjaan menyimpang, git checkout mengembalikan ke commit baik terakhir alih-alih mencoba men-debug state yang rusak.

Operasi file

Memproses data: wc -l *.csv && ls -lh *.csv
Mencari file: find . -name "*.py" | xargs grep "pattern"
Membuat backup: tar -czf backup.tar.gz ./data

Tugas sistem

Memeriksa sumber daya: df -h && free -m
Manajemen proses: ps aux | grep python
Penyiapan lingkungan: export PATH=$PATH:/new/path && echo $PATH

Keterbatasan

Tidak ada perintah interaktif: Tidak dapat menangani vim, less, atau prompt kata sandi
Tidak ada aplikasi GUI: Hanya baris perintah
Cakupan sesi: State sesi bash berada di sisi klien. API bersifat stateless. Aplikasi Anda bertanggung jawab untuk mempertahankan sesi shell di antara giliran.
Batas output: Output besar mungkin dipotong
Tidak ada streaming: Hasil dikembalikan setelah selesai

Menggabungkan dengan alat lain

Alat bash paling kuat ketika digabungkan dengan text editor dan alat lainnya.

Langkah selanjutnya

Ikhtisar penggunaan alat

Pelajari tentang penggunaan alat dengan Claude

Alat text editor

Lihat dan edit file teks dengan Claude

Was this page helpful?

Ikhtisar

Kasus penggunaan

Mulai cepat

Cara kerjanya

Parameter

Contoh penggunaan

Contoh: Otomatisasi multi-langkah

Mengimplementasikan alat bash

Menangani error

Timeout eksekusi perintah

Perintah tidak ditemukan

Izin ditolak

Ikuti praktik terbaik implementasi

Gunakan timeout perintah

Pertahankan state sesi

Tangani output besar

Catat semua perintah

Sanitasi output

Keamanan

Rekomendasi utama

Harga

Pola umum

Alur kerja pengembangan

Checkpointing berbasis Git

Operasi file

Tugas sistem

Keterbatasan

Menggabungkan dengan alat lain

Langkah selanjutnya

Ikhtisar

Kasus penggunaan

Mulai cepat

Cara kerjanya

Parameter

Contoh penggunaan

Contoh: Otomatisasi multi-langkah

Mengimplementasikan alat bash

Menangani error

Timeout eksekusi perintah

Perintah tidak ditemukan

Izin ditolak

Ikuti praktik terbaik implementasi

Gunakan timeout perintah

Pertahankan state sesi

Tangani output besar

Catat semua perintah

Sanitasi output

Keamanan

Rekomendasi utama

Harga

Pola umum

Alur kerja pengembangan

Checkpointing berbasis Git

Operasi file

Tugas sistem

Keterbatasan

Menggabungkan dengan alat lain

Langkah selanjutnya

Ikhtisar

Kasus penggunaan

Mulai cepat

Cara kerjanya

Parameter

Contoh: Otomatisasi multi-langkah

Mengimplementasikan alat bash

Menangani error

Ikuti praktik terbaik implementasi

Keamanan

Rekomendasi utama

Harga

Pola umum

Alur kerja pengembangan

Checkpointing berbasis Git

Operasi file

Tugas sistem

Keterbatasan

Menggabungkan dengan alat lain

Langkah selanjutnya

Ikhtisar

Kasus penggunaan

Mulai cepat

Cara kerjanya

Parameter

Contoh: Otomatisasi multi-langkah

Mengimplementasikan alat bash

Menangani error

Ikuti praktik terbaik implementasi

Keamanan

Rekomendasi utama

Harga

Pola umum

Alur kerja pengembangan

Checkpointing berbasis Git

Operasi file

Tugas sistem

Keterbatasan

Menggabungkan dengan alat lain

Langkah selanjutnya